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
| 