phenix_logo
Python-based Hierarchical ENvironment for Integrated Xtallography
Documentation Home
 

phenix.ensemble_refinement

List of all ensemble_refinement keywords

Purpose phenix.ensemble_refinement is designed to combine X-ray structure refinement with molecular dynamics in order to produce ensemble models fitted to diffraction data. These ensemble models can contain ~50-500 individual structures and simultaneously account for anisotopic and anharmonic distributions.

Burnley BT, Afonine PV, Adams PD, Gros P. 2012. Modelling dynamics in protein crystal structures by ensemble refinement. eLife 1:e00311. doi: 10.7554/elife.00311. In Press.

General Procedure The input structure should be a final completed single structure model (e.g. publication ready). If TLS is used the TLS components must be present in the atom records (see phenix.tls). For optimal use explicit hydrogen should be added using either phenix.ready_set or phenix.pdbtools. The simulation is launched using the command line:

% phenix.ensemble_refinement model.pdb data.mtz [ligands.cif] [parameters]

For non-covalent ligands (excluding waters) it is recommended to use harmonic restraints e.g.:

% phenix.ensemble_refinement model.pdb data.mtz er_harmonic_restraints_selections=’resname PO4 and element P’

Parameter Optimisation There are three main empirical parameters should be optimised.

(1) pTLS:

% phenix.ensemble_refinement x.pdb x.mtz ptls=0.7

Defines the fraction of atoms included in the TLS fitting procedure (see Burnley et al. 2012). The optimum value for this parameter cannot be determined a priori. Setting up an array of simultaneous simulations with different values (e.g. 1.0, 0.9, 0.8, 0.6) is recommended. By default the TLS groups are applied to each separate chain. TLS groups can be user defined using:

% phenix.ensemble_refinement x.pdb x.mtz tls_group_selections=chain a tls_group_selections=chain b

Excessive numbers of TLS groups will result in intramolecular disorder being absorbed by the TLS B-factors rather than being modelled by atomic fluctuations in the simulation therefore it is recommended to use as few as possible, e.g. one per chain (see Burnley et al. 2012). The TLS fitting process requires that the number of non-hydrogen non-solvent atoms per TLS group * ptls to be greater than 63, otherwise ptls is automatically increased. If any TLS group has less than 63 non-solvent, non-hydrogen atoms then an isotropic model, based on the Wilson B-factor, is automatically applied.

(2) wxray_coupled_tbath_offset:

% phenix.ensemble_refinement x.pdb x.mtz wxray_coupled_tbath_offset=10.0

Unintuitively wxray_coupled_tbath_offset controls the X-ray weight. The X-ray weight is modulated in situ such that the simulation runs at the target temperature (cartesian_dynamics.temperature). The simulation uses velocity scaling to maintain the target temperature. This is coupled to a temperature thermostat which is set as:

thermostat = cartesian_dynamics.temperature - wxray_coupled_tbath_offset

The non-conservative X-ray force generates heat (see Burnley et al 2012), thus a larger offset increases the X-ray weight. The default value is 5 K. For example values of 2.5 and 10 K may also be tested.

(3) tx:

% phenix.ensemble_refinement x.pdb x.mtz tx=1.0

The relaxation time (or memory time) in picoseconds of the time-averaged restraints used in the simulation. As tx increases more structures contribute to the target function (see Burnley et al. 2012 for more details) and the optimum value is correlated with resolution (see Burnley et al. 2012). If tx is not defined (tx = None) a value will be automatically selected based on the dataset resolution. Values of 2 x automated Tx and 0.5 x automated Tx may also be tested. N.B. the simulation time is based on tx, larger values of tx will produce longer simulations.

The default parameters have been set to give best as possible results. However, it is strongly recommend that pTLS is optimised on a case by base basis and it may be necessary to optimise the temperature bath offset followed by tx.

List of all ensemble_refinement keywords:

List of all ensemble_refinement 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
------------------------------------------------------------------------------- 
extra_restraints_file= None File containing custom geometry restraints, using
                       the same format as phenix.refine. On the command line
                       this can be specified directly as a command-line
                       argument, but this parameter is used by the Phenix GUI.
input
   sequence= None
   skip_twin_detection= False
   scattering_table= wk1995 it1992 *n_gaussian neutron
   xray_data Scope of X-ray data and free-R flags
      file_name= None
      labels= None
      high_resolution= None
      low_resolution= None
      outliers_rejection= True Remove basic wilson outliers , extreme wilson
                          outliers , and beamstop shadow outliers
      french_wilson_scale= True
      sigma_fobs_rejection_criterion= None
      sigma_iobs_rejection_criterion= None
      ignore_all_zeros= True
      force_anomalous_flag_to_be_equal_to= None
      french_wilson
         max_bins= 60 Maximum number of resolution bins
         min_bin_size= 40 Minimum number of reflections per bin
      r_free_flags
         file_name= None This is normally the same as the file containing Fobs
                    and is usually selected automatically.
         label= None
         test_flag_value= None This value is usually selected automatically -
                          do not change unless you really know what you're
                          doing!
         ignore_r_free_flags= False Use all reflections in refinement (work
                              and test)
         disable_suitability_test= False
         ignore_pdb_hexdigest= False If True, disables safety check based on
                               MD5 hexdigests stored in PDB files produced by
                               previous runs.
         generate= False Generate R-free flags (if not available in input
                   files)
         fraction= 0.1
         max_free= 2000
         lattice_symmetry_max_delta= 5
         use_lattice_symmetry= True
         use_dataman_shells= False Used to avoid biasing of the test set by
                             certain types of non-crystallographic symmetry.
         n_shells= 20
   pdb
      file_name= None Model file(s) name (PDB)
   monomers
      file_name= None Monomer file(s) name (CIF)
ensemble_refinement
   update_sigmaa_rfree= 0.001 test function
   ensemble_reduction= True Find miminium number of structures to reproduce
                       simulation R-values
   verbose= -1
   output_file_prefix= None Prefix for all output files
   gzip_final_model= True
   random_seed= 2679941 Random seed
   nproc= 1
   tx= None Relaxation time (ps)
   equilibrium_n_tx= 10 Length of equilibration period, n times tx
   acquisition_block_n_tx= 2 Length of acquisition block, n times tx
   number_of_acquisition_periods= 10 Number of acquisition periods
   pdb_stored_per_block= 50 Number of model coordinates stored per acquisition
                         block
   wxray_coupled_tbath= True Use temperature control wxray
   wxray_coupled_tbath_offset= 5.0 Temperature offset, increasing offset
                               increases wxray
   wxray= 1.0 Multiplier for xray weighting; used if wxray_coupled_tbath =
          Flase
   tls_group_selections= None TLS groups to use for TLS fitting (TLS details
                         in PDB header not used)
   ptls= 0.80 The fraction of atoms to include in TLS fitting
   max_ptls_cycles= 25 Maximum cycles to use in TLS fitting; TLS will stop
                    prior to this if convergence is reached
   isotropic_b_factor_model= False Use isotropic B-factor model instead of TLS
   pwilson= 0.8 Scale factor for isotropic b-factor model: all atoms = Bwilson
            * pwilson
   set_occupancies= False Set all atoms aoccupancy to 1.0
   target_name= *ml ls_wunit_k1_fixed ls_wunit_k1 Choices for refinement target
   remove_alt_conf_from_input_pdb= True Removes any alternative conformations
                                   if present in input PDB model
   scale_wrt_n_calc_start= False Scale  to starting Ncalc
   show_wilson_plot= False Print Wilson plot during simulation
   output_running_kinetic_energy_in_occupancy_column= False Output PDB file
                                                      contains running kinetic
                                                      energy in place of
                                                      occupancy
   ordered_solvent_update= True Ordered water molecules automatically updated
                           every nth macro cycle
   ordered_solvent_update_cycle= 25 Number of macro-cycles per ordered solvent
                                 update
   cartesian_dynamics
      temperature= 300
      number_of_steps= 10
      time_step= 0.0005
      initial_velocities_zero_fraction= 0
      n_print= 100
      verbose= -1
      protein_thermostat= True Use protein atoms thermostat
   harmonic_restraints
      selections= None Atoms selections to apply harmonic restraints
      weight= 0.001 Harmonic restraints weight
      slack= 1.0 Harmonic restraints slack distance
   electron_density_maps
      apply_default_maps= True
      map_coefficients
         map_type= None
         format= *mtz phs
         mtz_label_amplitudes= None
         mtz_label_phases= None
         kicked= False
         fill_missing_f_obs= False
         acentrics_scale= 2.0 Scale terms corresponding to acentric
                          reflections (residual maps only: k==n)
         centrics_pre_scale= 1.0 Centric reflections, k!=n and k*n != 0:
                             max(k-centrics_pre_scale,0)*Fo-max(n-centrics_pre_
                            scale,0)*Fc
         sharpening= False Apply B-factor sharpening
         sharpening_b_factor= None Optional sharpening B-factor value
         exclude_free_r_reflections= False Exclude free-R selected reflections
                                     from output map coefficients
         isotropize= True
         dev
            complete_set_up_to_d_min= False
            aply_same_incompleteness_to_complete_set_at= randomly low high
   mask
      use_asu_masks= True
      solvent_radius= 1.11
      shrink_truncation_radius= 0.9
      grid_step_factor= 4.0 The grid step for the mask calculation is
                        determined as highest_resolution divided by
                        grid_step_factor. This is considered as suggested
                        value and may be adjusted internally based on the
                        resolution.
      verbose= 1
      mean_shift_for_mask_update= 0.001 Value of overall model shift in
                                  refinement to updates the mask.
      ignore_zero_occupancy_atoms= True Include atoms with zero occupancy into
                                   mask calculation
      ignore_hydrogens= False Ignore H or D atoms in mask calculation
      n_radial_shells= 1 Number of shells in a radial shell bulk solvent model
      radial_shell_width= 1.5 Radial shell width
   ensemble_ordered_solvent
      diff_map_cutoff= 2.5
      e_map_cutoff_keep= 0.5
      e_map_cutoff_find= 0.5
      tolerance= 0.9
      ordered_solvent_map_to_model= True
      output_residue_name= HOH
      output_chain_id= S
      output_atom_name= O
      scattering_type= O Defines scattering factors for newly added waters
      primary_map_type= mFo-DFmodel
      primary_map_cutoff= 3.0
      secondary_map_type= 2mFo-DFmodel
      secondary_map_cutoff_keep= 1.0
      secondary_map_cutoff_find= 1.0
      h_bond_min_mac= 1.8
      h_bond_min_sol= 1.8
      h_bond_max= 3.2
      new_solvent= *isotropic anisotropic Based on the choice, added solvent
                   will have isotropic or anisotropic b-factors
      b_iso_min= 0.0 Minimum B-factor value, waters with smaller value will be
                 rejected
      b_iso_max= 100.0 Maximum B-factor value, waters with bigger value will
                 be rejected
      anisotropy_min= 0.1 For solvent refined as anisotropic: remove is less
                      than this value
      b_iso= None Initial B-factor value for newly added water
      occupancy_min= 0.1 Minimum occupancy value, waters with smaller value
                     will be rejected
      occupancy_max= 1.0 Maximum occupancy value, waters with bigger value
                     will be rejected
      occupancy= 1.0 Initial occupancy value for newly added water
      refine_occupancies= False Refine solvent occupancies.
      add_hydrogens= False Adds hydrogens to water molecules (except those on
                     special positions)
      refilter= True
      temperature= 300 Target temperature for random velocity assignment
      seed= 343534534 Fixes the random seed for velocity assignment
      preserved_solvent_minimum_distance= 7.0
      find_peaks
         use_sigma_scaled_maps= True Default is sigma scaled map, map in
                                absolute scale is used otherwise.
         resolution_factor= 1./4.
         max_number_of_peaks= None
         map_next_to_model
            min_model_peak_dist= 1.8
            max_model_peak_dist= 3.0
            min_peak_peak_dist= 1.8
            use_hydrogens= False
         peak_search
            peak_search_level= 1
            max_peaks= 0
            interpolate= True
            min_distance_sym_equiv= None
            general_positions_only= False
            min_cross_distance= 1.8
            min_cubicle_edge= 5
refinement
   geometry_restraints
      edits
         excessive_bond_distance_limit= 10
         bond
            action= *add delete change
            atom_selection_1= None
            atom_selection_2= None
            symmetry_operation= None The bond is between atom_1 and
                                symmetry_operation * atom_2, with atom_1 and
                                atom_2 given in fractional coordinates.
                                Example: symmetry_operation = -x-1,-y,z
            distance_ideal= None
            sigma= None
            slack= None
         angle
            action= *add delete change
            atom_selection_1= None
            atom_selection_2= None
            atom_selection_3= None
            angle_ideal= None
            sigma= None
         planarity
            action= *add delete change
            atom_selection= None
            sigma= None
         scale_restraints Apply a scale factor to restraints for specific atom
                          selections, to tighten geometry without changing the
                          overall scale of the geometry target.
            atom_selection= None
            scale= 1.0
            apply_to= *bond *angle *dihedral *chirality
gui Phenix GUI parameters, not used in command-line program
   job_title= None Job title in PHENIX GUI, not used on command line
   output_dir= None