Structure refinement in PHENIX
- Available features
- Current limitations
- phenix.refine organization
- Running phenix.refine
- Refinement with all default parameters
- Giving parameters on the command line or in files
- Refinement scenarios
- Refinement of coordinates
- Refinement of atomic displacement parameters (commonly named as ADP or B-factors)
- Occupancy refinement
- f' and f'' refinement
- Using NCS restraints in refinement
- Water picking
- Hydrogens in refinement
- Refinement using twinned data
- Neutron and joint X-ray and neutron refinement
- Examples of frequently used refinement protocols, common problems
- Useful options
- Changing the number of refinement cycles and minimizer iterations
- Creating R-free flags (if not present in the input reflection files)
- Specify the name for output files
- Reflection output
- Setting the resolution range for the refinement
- Bulk solvent correction and anisotropic scaling
- Default refinement with user specified X-ray target function
- Modifying the initial model before refinement starts
- Refinement using FFT or direct structure factor calculation algorithm
- Ignoring test (free) flags in refinement
- Using phenix.refine to calculate structure factors
- Scattering factors
- Suppressing the output of certain files
- Random seed
- Electron density maps
- Refining with anomalous data (or what phenix.refine does with Fobs+ and Fobs-).
- Rejecting reflections by sigma
- Developer's tools
- CIF modifications and links
- Definition of custom bonds and angles
- Atom selection examples
- Referencing phenix.refine
- Relevant reading
- Questions, problems, bugs, more information
- List of all refinement keywords
phenix.refine is the general purpose crystallographic structure refinement program
Available features
- Coordinate refinement:
- Restrained / unrestrained individual
- Grouped (rigid body)
- LBFGS minimization, Simulated Annealing
- Selective removing of stereochemistry restraints
- Adding custom bonds and angles
- Atomic Displacement Parameters (ADP) refinement:
- Restrained individual isotropic, anisotropic, mixed
- Group isotropic (one isotropic B per selected model part)
- TLS
- comprehensive mode: combined TLS + individual or group ADP
- Occupancy refinement (individual or group)
- Anomalous f' and f'' refinement
- Bulk solvent correction (flat model using a mask) and anisotropic scaling
- Multiple refinement and scale target functions: least-squares (ls), maximum-likelihood (ml), phased maximum-likelihood (mlhl)
- FFT and direct summation based refinement
- Various electron density map calculations (including likelihood-weighted)
- Simple structure factor calculation (with or without bulk solvent and scaling)
- Combined automatic ordered solvent building, update and refinement
- Complete model and data statistics (including twinning analysis, Wilson B calculation, stereo-chemistry statistics and much more)
- Automatic detection of NCS related copies and building NCS restraints
- Refinement using X-ray, neutron or both experimental data
- Complex refinement strategies in one run
- Refinement at subatomic resolution (approx. < 1.0 A) with IAS model
- Refinement with twinned data
Current limitations
- No omit maps calculation (use PHENIX wizards for this)
- TLS and individual anisotropic ADP cannot be refined at once for the same group
- No specific constraints for occupancies of atoms in alternative conformations
- Certain refinement strategies are not available for joint X-ray/neutron refinement
- No NCS constraints (restraints only)
- No selective removing of bond restraints
- Atoms with anisotropic ADP in NCS groups
- No selected bond restraints removing
Remark on using amplitudes (Fobs) vs intensities (Iobs)
Although phenix.refine can read in both data types, intensities or amplitudes, internally it uses amplitudes in nearly all calculations. Both ways of doing refinement, with Iobs or Fobs, have their own slight advantages and disadvantages. To our knowledge there is no strong points to argue using one data type w.r.t. another.
phenix.refine organization
A refinement run in phenix.refine always consists of three main steps: reading in and processing of the data (model in PDB format, reflections in most known formats, parameters and optionally cif files with stereochemistry definitions), performing requested refinement protocols (bulk solvent and scaling, refinement of coordinates and B-factors, water picking, etc...) and finally writing out refined model, complete refinement statistics and electron density maps in various formats. The figure below illustrates these steps:
The second central step encompassing from bulk solvent correction and scaling to refinement of particular model parameters is called macro-cycles and repeated several times (3 by default). Multiple refinement scenario can be realized at this step and applied to any selected part of a model as illustrated at figure below:
Running phenix.refine
phenix.refine is run from the command line:
% phenix.refine <pdb-file(s)> <reflection-file(s)> <monomer-library-file(s)>
When you do this a number of things happen:
- The program automatically generates a ".eff" file which contains all of the parameters for the job (for example if you provided lysozyme.pdb the file lysozyme_refine_001.eff will be generated). This is the set of input parameters for this run.
- The program automatically interprets the reflection file(s). If there is an unambiguous choice of data arrays these will be used for the refinement. If there is a choice, you're given a message telling you how to select the arrays. Several reflection files can be provided, for example: one containing Fobs and another one with R-free flags.
- Once the data arrays are chosen, the program writes all of the data it will be using in the refinement to a new MTZ file, for example, lysozyme_refine_data.mtz. This makes it very easy to keep track of what you actually used in the refinement (instead of having the arrays spread across multiple files).
- At the end of refinement the program generates:
a new PDB file, with the refined model, called for example lysozyme_refine_001.pdb;
two maps: likelihood weighted mFo-DFc and 2mFo-DFc. These are in ASCII X-PLOR format. A reflection file with map coefficients is also generated for use in Coot or XtalView (e.g. lysozyme_refine_001_map_coeffs.mtz);
a new defaults file to run the next cycle of refinement, e.g. lysozyme_refine_002.def. This means you can run the next cycle of refinement by typing:
% phenix.refine lysozyme_refine_002.def
To get information about command line options type:
% phenix.refine --help
To have the program generate the default input parameters without running the refinement job (e.g. if you want to modify the parameters prior to running the job):
% phenix.refine --dry_run <pdb-file> <reflection-file(s)>
If you know the parameter that you want to change you can override it from the command line:
% phenix.refine data.hkl model.pdb main.low_resolution=8.0 \ simulated_annealing.start_temperature=5000
Note that you don't have to specify the full parameter name. What you specify on the command line is matched against all known parameters names and the best substring match is used if it is unique.
To rerun a job that was previously run:
% phenix.refine --overwrite lysozyme_refine_001.def
The --overwrite option allows the program to overwrite existing files. By default the program will not overwrite existing files - just in case this would remove the results of a refinement job that took a long time to finish.
To see all default parameters:
% phenix.refine --show-defaults=all
Refinement with all default parameters
% phenix.refine data.hkl model.pdb
This will perform coordinate refinement and restrained ADP refinement. Three macrocycles will be executed, each consisting of bulk solvent correction, anisotropic scaling of the data, coordinate refinement (25 iterations of the LBFGS minimizer) and ADP refinement (25 iterations of the LBFGS minimizer). At the end the updated coordinates, maps, map coefficients, and statistics are written to files.
Giving parameters on the command line or in files
In phenix.refine parameters to control refinement can be given by the user on the command line:
% phenix.refine data.hkl model.pdb simulated_annealing=true
However, sometimes the number of parameters is large enough to make it difficult to type them all on the command line, for example:
% phenix.refine data.hkl model.pdb refine.adp.tls="chain A" \ refine.adp.tls="chain B" main.number_of_macro_cycles=4 \ main.high_resolution=2.5 wxc_scale=3 wxu_scale=5 \ output.prefix=my_best_model strategy=tls+individual_sites+individual_adp \ simulated_annealing.start_temperature=5000
The same result can be achieved by using:
% phenix.refine data.hkl model.pdb custom_par_1.params
where the custom_par_1.params file contains the following lines:
refinement.refine.strategy=tls+individual_sites+individual_adp refinement.refine.adp.tls="chain A" refinement.refine.adp.tls="chain B" refinement.main.number_of_macro_cycles=4 refinement.main.high_resolution=2.5 refinement.target_weights.wxc_scale=3 refinement.target_weights.wxu_scale=5 refinement.output.prefix=my_best_model refinement.simulated_annealing.start_temperature=5000
which can also be formatted by grouping the parameters under the relevant scopes (custom_par_2.params):
refinement.main {
number_of_macro_cycles=4
high_resolution=2.5
}
refinement.refine {
strategy = *individual_sites \
rigid_body \
*individual_adp \
group_adp \
*tls \
individual_occupancies \
group_occupancies \
group_anomalous \
none
adp {
tls = "chain A"
tls = "chain B"
}
}
refinement.target_weights {
wxc_scale=3
wxu_scale=5
}
refinement.output.prefix=my_best_model
refinement.simulated_annealing.start_temperature=5000
and the refinement run will be:
% phenix.refine data.hkl model.pdb custom_par_2.params
The easiest way to create a file like the custom_par_2.params file is to generate a template file containing all parameters by using the command phenix.refine --show-defaults=all and then take the parameters that you want to use (and remove the rest).
Refinement scenarios
The refinement of atomic parameters is controlled by the strategy keyword. Those include:
- individual_sites (refinement of individual atomic coordinates) - individual_adp (refinement of individual atomic B-factors) - group_adp (group B-factors refinement) - group_anomalous (refinement of f' and f" values) - tls (TLS refinement = refinement of ADP through TLS parameters) - rigid_body (rigid body refinement) - none (bulk solvent and anisotropic scaling only)
Below are examples to illustrate the use of the strategy keyword as well as a few others.
Refinement of coordinates
phenix.refine offers three ways of coordinate refinement:
- individual coordinate refinement using gradient-driven (LBFGS) minimization;
- individual coordinate refinement using simulated annealing (SA refinement);
- grouped coordinate refinement (rigid body refinement).
All types of coordinate refinement listed above can be used separately or combined all together in any combination and can be applied to any selected part of a model. For example, if a model contains three chains A, B and C, than it would require only one single refinement run to perform SA refinement and minimization for atoms in chain A, rigid body refinement with two rigid groups A and B, and refine nothing for chain C. Below we will illustrate this with several examples.
The default refinement includes a standard set of stereo-chemical restraints ( covalent bonds, angles, dihedrals, planarities, chiralities, non-bonded). The NCS restrains can be added as well. Completely unrestrained refinement is possible.
The total refinement target is defined as:
Etotal = wxc_scale * wxc * Exray + wc * Egeom
where: Exray is crystallographic refinement target (least-squares, maximum-likelihood, or any other), Egeom is the sum of restraints (including NCS if requested), wc is 1.0 by default and used to turn the restraints off, wxc ~ ratio of gradient's norms for geometry and X-ray targets as defined in (Adams et al, 1997, PNAS, Vol. 94, p. 5018), wc_scale is an 'ad hoc' scale found empirically to be ok for most of the cases.
When a refinement of coordinates (individual or rigid body) is run without using selections, then the coordinates of all atoms will be refined. Otherwise, if selections are used, the only coordinates of selected atoms will be refined and the rest will be fixed.
Using strategy=rigid_body or strategy=individual_sites will ask phenix.refine to refine only coordinates while other parameters (ADP, occupancies) will be fixed.
phenix.refine will stop if an atom at special position is included in rigid body group. The solution is to make a new rigid body group selection containing no atoms at special positions.
Rigid body refinement
phenix.refine implementation of rigid body refinement is very sophisticated and efficient (big convergence radius, one run, no need to cut off high-resolution data). We call this MZ protocol (multiple zones). The essence of MZ protocol is that the refinement starts with a few reflections selected in the lowest resolution zone and proceeds with gradually adding higher resolution reflections. Also, it almost constantly updates the mask and bulk solvent model parameters and this is crucial since the bulk solvent affects the low resolution reflections - exactly those the most important for success of rigid body refinement. The default set of the rigid body parameters is good for most of the cases and is normally not supposed to be changed.
One rigid body group (whatever is in the PDB file is refined as a single rigid body):
% phenix.refine data.hkl model.pdb strategy=rigid_body
Multiple groups (requires a basic knowledge of the PHENIX atom selection language, see below):
% phenix.refine data.hkl model.pdb strategy=rigid_body \ sites.rigid_body="chain A" sites.rigid_body="chain B"
This will refine the chain A and chain B as two rigid bodies. The rest of the model will be kept fixed.
If one have many rigid groups, a lot of typing in the command line may not be convenient, so creating a parameter file rigid_body_selections, containing the following lines, may be a good idea:
refinement.refine.sites { rigid_body = chain A rigid_body = chain B }The command line will then be:
% phenix.refine data.hkl model.pdb strategy=rigid_body rigid_body_selections.params
Files like this can be created, for example, by copy-and-paste from the complete list of parameters (phenix.refine --show-defaults=all).
To switch from MZ protocol to traditional way of doing rigid body refinement (not recommended!):
% phenix.refine data.hkl model.pdb strategy=rigid_body rigid_body.protocol=one_zone \ rigid_body.high_resolution=4.0
Note that doing one zone refinement one need to cut the high-resolution data off at some arbitrary point around 3-5 A (depending on model size and data quality).
By default the rigid body refinement is run only the first macro-cycles. To switch from running rigid body refinement only once at the first macro-cycle to running it every macro-cycle:
% phenix.refine data.hkl model.pdb strategy=rigid_body rigid_body.mode=every_macro_cycle
To change the default number of lowest resolution reflections used to determine the first resolution zone to do rigid body refinement in it (for MZ protocol only):
% phenix.refine data.hkl model.pdb strategy=rigid_body \ rigid_body.min_number_of_reflections=250
Decreasing this number may increase the convergence radius of rigid body refinement but small numbers may lead to refinement instability.
To change the number of zones for MZ protocol:
% phenix.refine data.hkl model.pdb strategy=rigid_body \ rigid_body.number_of_zones=7
Increasing this number may increase the convergence radius of rigid body refinement at the cost of much longer run time.
Refinement of individual coordinates
Refinement with Simulated Annealing:
% phenix.refine data.hkl model.pdb simulated_annealing=true \ strategy=individual_sites
This will perform the Simulated Annealing refinement and LBFGS minimization for the whole model.
To change the start SA temperature:
% phenix.refine data.hkl model.pdb simulated_annealing=true \ strategy=individual_sites simulated_annealing.start_temperature=10000
Since a SA run may take some time, there are several options defining of how many times the SA will be performed per refinement run. Run it only the first macro_cycle:
% phenix.refine data.hkl model.pdb simulated_annealing=true \ strategy=individual_sites simulated_annealing.mode=first
% phenix.refine data.hkl model.pdb simulated_annealing=true \ strategy=individual_sites simulated_annealing.mode=every_macro_cycle
or second and before the last macro-cycle:
% phenix.refine data.hkl model.pdb simulated_annealing=true \ strategy=individual_sites simulated_annealing.mode=second_and_before_last
Refinement with minimization (whole model):
% phenix.refine data.hkl model.pdb strategy=individual_sites
Refinement with minimization (selected part of model):
% phenix.refine data.hkl model.pdb strategy=individual_sites \ sites.individual="chain A"
This will refine the coordinates of atoms in chain A while keeping fixed the atomic coordinates in chain B.
To perform unrestrained refinement of coordinates (usually at ultra-high resolutions):
% phenix.refine data.hkl model.pdb strategy=individual_sites wc=0
This assigns the contribution of the geometry restraints target to zero. However, it is still calculated for statistics output.
Removing selected geometry restraints
% phenix.refine data.hkl model.pdb remove_restraints_selections.params
where remove_restraints_selections.params contains:
refinement { geometry_restraints.remove { angles = chain B dihedrals = name CA chiralities = all planarities = None } }the following restraints will be removed: angle for all atoms in chain B, dihedral for all involving CA atoms, all chirality. All planarity restraints will be preserved.
Refinement of atomic displacement parameters (commonly named as ADP or B-factors)
An ADP in phenix.refine is defined as a sum of three contributions:
Utotal = Ulocal + Utls + Ucryst
where Utotal is the total ADP, Ulocal reflects the local atomic vibration (also named as residual B) and Ucryst reflects global lattice vibrations. Ucryst is determined and refined at anisotropic scaling stage.
phenix.refine offers multiple choices for ADP refinement:
- individual isotropic, anisotropic or mixed ADP;
- grouped with one isotropic ADP per selected group;
- TLS.
All types of ADP refinement listed above can be used separately or combined all together in any combination (except TLS+individual anisotropic) and can be applied to any selected part of a model. For example, if a model contains six chains A, B, C, D, E and F than it would require only one single refinement run to perform refinement of:
- individual isotropic ADP for atoms in chain A, - individual anisotropic ADP for atoms in chain B, - grouped B with one B per residue for chain C, - TLS refinement for chain D, - TLS and individual isotropic refinement for chain E, - TLS and grouped B refinement for chain F.
Below we will illustrate this with several examples.
Restraints are used for default ADP refinement of isotropic and anisotropic atoms. Completely unrestrained refinement is possible.
The total refinement target is defined as:
Etotal = wxu_scale * wxu * Exray + wu * Eadp
where: Exray is crystallographic refinement target (least-squares, maximum-likelihood, ...), Eadp is the ADP restraints term, wu is 1.0 by default and used to turn the restraints off, wxu and wc_scale are defined similarly to coordinates refinement (see Refinement of Coordinates paragraph).
It is important to keep in mind:
If a model was previously refined using TLS that means all atoms participating in TLS groups are reported in output PDB file as anisotropic (have ANISOU records). Now if a PDB file like this is submitted for default refinement then all atoms with ANISOU records will be refined as individual anisotropic which is most likely not desired.
When performing TLS refinement along with individual isotropic refinement of Ulocal, the restraints are applied to Ulocal and not to the total ADP (Ulocal+Utls).
When performing group B or TLS refinement only, no ADP restrains is used.
When ADP refinement is run without using selections then ADP for all atoms will be refined. Otherwise, if selections are used, the only ADP of selected atoms will be refined and the ADP of the rest will be unchanged.
If a TLS parametrization is used for a model previously refined with individual anisotropic ADP then normally an increase of R-factors is expected.
phenix.refine will stop if an atom at special position is included in TLS group. The solution is to make a new TLS group selection containing no atoms at special positions.
When refining TLS, the output PDB file always has the ANISOU records for the atoms involved in TLS groups. The anisotropic B-factor in ANISOU records is the total B-factor (B_tls + B_individual). The isotropic equivalent B-factor in ATOM records is the mean of the trace of the ANISOU matrix divided by 10000 and multiplied by 8*pi^2 and represents the isotropic equivalent of the total B-factor (B_tls + B_individual). To obtain the individual B-factors, one needs to compute the TLS component (B_tls) using the TLS records in the PDB file header and then subtract it from the total B-factors (on the ANISOU records).
Refining group isotropic B-factors
One B-factor per residue:
% phenix.refine data.hkl model.pdb strategy=group_adp
One isotropic B per selected group of atoms:
% phenix.refine data.hkl model.pdb strategy=group_adp \ one_adp_group_per_residue=false adp.group="chain A" adp.group="chain B"
This will refine one isotropic B for chain A and one B for chain B.
The refinement of group isotropic B-factors in phenix.refine does not change the original distribution of B-factors within the group, that is the differences between B-factors for atoms withing the group remain constant while the only total component added to all atoms of given group is varied. The atoms with anisotropic ADP are allowed to be withing the group.
Refinement of individual ADP (isotropic, anisotropic)
By default atoms in a PDB file with ANISOU records are refined as anisotropic and atoms without ANISOU records are refined as isotropic. This behavior can be changed with appropriate keywords.
Default refinement of individual ADP:
% phenix.refine data.hkl model.pdb strategy=individual_adp
Note, atoms in input PDB file with ANISOU records will be refined as anisotropic and those without ANISOU - as isotropic.
Refinement of individual isotropic ADP for a model previously refined as anisotropic or TLS:
% phenix.refine data.hkl model.pdb strategy=individual_adp \ adp.individual.isotropic=all
% phenix.refine data.hkl model.pdb strategy=individual_adp \ convert_to_isotropic=true
All anisotropic atoms in input PDB file will be converted to isotropic before the refinement starts. Obviously, this may raise the R-factors.
Refinement of individual anisotropic ADP for a model previously refined as isotropic:
% phenix.refine data.hkl model.pdb strategy=individual_adp \ adp.individual.anisotropic="not element H"
Refinement of mixed model (some atoms are isotropic, some are anisotropic):
% phenix.refine data.hkl model.pdb strategy=individual_adp \ adp.individual.anisotropic="chain A and not element H" \ adp.individual.isotropic="chain B or element H"
In this example the atoms (except hydrogens if any) in chain A will be refined as anisotropic and the atoms in chain B (and hydrogens if any) will be refined as isotropic. Often, the ADP of water and hydrogens are desired to be refined as isotropic while the other atoms - as anisotropic:
% phenix.refine data.hkl model.pdb strategy=individual_adp \ adp.individual.anisotropic="not water and not element H" \ adp.individual.isotropic="water or element H"
Exactly the same command using slightly shorter selection syntax:
% phenix.refine data.hkl model.pdb strategy=individual_adp \ adp.individual.anisotropic="not (water or element H)" \ adp.individual.isotropic="water or element H"
To perform unrestrained individual ADP refinement (usually at ultra-high resolutions):
% phenix.refine data.hkl model.pdb strategy=individual_adp wu=0
This assigns the contribution of the ADP restraints target to zero. However, it is still calculated for statistics output.
TLS refinement
Refinement of TLS parameters only (whole model as one TLS group):
% phenix.refine data.hkl model.pdb strategy=tls
Refinement of TLS parameters only (multiple TLS group):
% phenix.refine data.hkl model.pdb strategy=tls tls_group_selections.params
where, similar to the rigid body or group B-factor refinement, the selection for TLS groups has been made in a user-created parameter file (tls_group_selections.params) as following:
refinement.refine.adp { tls = chain A tls = chain B }Alternatively, the selection for the TLS groups can be made from the command line (see rigid body refinement for an example).
Note: TLS parameters will be refined only for selected fragments. This, for example, will allow to not include the solvent molecules into the TLS groups.
More complete is to perform combined TLS and individual or grouped isotropic ADP refinement:
% phenix.refine data.hkl model.pdb strategy=tls+individual_adp
% phenix.refine data.hkl model.pdb strategy=tls+group_adp
This will allow to model global (TLS) and local (individual) components of the total ADP and also compensate for the model parts where TLS parametrization doesn't suite well.
Occupancy refinement
Refinement of occupancies for all atoms in the model:
% phenix.refine data.hkl model.pdb strategy=individual_occupancies
Refinement of occupancies for selected atoms only:
% phenix.refine data.hkl model.pdb strategy=individual_occupancies \ refine.occupancies.individual="water or element H"
In the example above, the only occupancies of waters and H atoms will be refined.
Refinement of one occupancy factor per selected group of atoms (group occupancy refinement):
% phenix.refine data.hkl model.pdb strategy=group_occupancies \ refine.occupancies.group="chain A and resid 1"
f' and f'' refinement
If the structure contains anomalous scatterers (e.g. Se in a SAD or MAD experiment), and if anomalous data are available, it is possible to refine the dispersive (f') and anomalous (f") scattering contributions (see e.g. Ethan Merritt's tutorial for more information). In phenix.refine, each group of scatterers with common f' and f" values is defined via an anomalous_scatterers scope, e.g.:
refinement.refine.anomalous_scatterers {
group {
selection = name BR
f_prime = 0
f_double_prime = 0
refine = *f_prime *f_double_prime
}
}
NOTE: The refinement of the f' and f" values is carried out only if group_anomalous is included under refine.strategy! Otherwise the values are simply used as specified but not refined. So the refinement run with the parameters above included into group_anomalous_1.params:
% phenix.refine model.pdb data_anom.hkl group_anomalous_1.params \ strategy=individual_sites+individual_adp+group_anomalous
If required, multiple scopes can be specified, one for each unique pair of f' and f" values. These values are assigned to all selected atoms (see below for atom selection details). Often it is possible to start the refinement from zero. If the refinement is not stable, it may be necessary to start from better estimates, or even to fix some values. For example (file group_anomalous_2.params):
refinement.refine.anomalous_scatterers {
group {
selection = name BR
f_prime = -5
f_double_prime = 2
refine = f_prime *f_double_prime
}
}
% phenix.refine model.pdb data_anom.hkl group_anomalous_2.params \
strategy=individual_sites+individual_adp+group_anomalous
Here f' is fixed at -5 (note the missing * in front of f_prime in the refine definition), and the refinement of f" is initialized at 2.
The phenix.form_factor_query command is available for obtaining estimates of f' and f" given an element type and a wavelength, e.g.:
% phenix.form_factor_query element=Br wavelength=0.8 Information from Sasaki table about Br (Z = 35) at 0.8 A fp: -1.0333 fdp: 2.9928
Run without arguments for usage information:
% phenix.form_factor_query
Using NCS restraints in refinement
phenix.refine can find NCS automatically or use NCS selections defined by the user. Gaps in selected sequences are allowed - a sequence alignment is performed to detect insertions or deletions. We recommend to check the automatically detected or adjusted NCS groups.
Refinement with user provided NCS selections.
Create a ncs_groups.params file with the NCS selections:
refinement.ncs.restraint_group { reference = chain A resid 1:4 selection = chain B and resid 1:3 selection = chain C } refinement.ncs.restraint_group { reference = chain E selection = chain F }Specify ncs_groups.params as an additional input when running phenix.refine:
% phenix.refine data.hkl model.pdb ncs_groups.params main.ncs=True
This will perform the default refinement round (individual coordinates and B-factors) using NCS restraints on coordinates and B-factors.
Note: user specified NCS restraints in ncs_groups.params can be modified automatically if better selection is found. To disable this potential automatic adjustment:
% phenix.refine data.hkl model.pdb ncs_groups.params main.ncs=True \ ncs.find_automatically=False
Automatic detection of NCS groups:
% phenix.refine data.hkl model.pdb main.ncs=True
This will perform the default refinement round (individual coordinates and B-factors) using NCS restraints automatically created based on input PDB file.
Water picking
phenix.refine has very efficient and fully automated protocol for water picking and refinement. One run of phenix.refine is normally necessary to locate waters, refine them, select good ones, add new and refine again, repeating the whole process multiple times.
Normally, the default parameter settings are good for most cases:
% phenix.refine data.hkl model.pdb ordered_solvent=true
This will perform new water picking, analysis of existing waters and refinement of individual coordinates and B-factors for both, macromolecule and waters. Several cycles will be performed allowing sorting out of spurious waters and refinement of well placed ones.
Water picking can be combined with all others protocols, like simulated annealing, TLS refinement, etc. Some useful commands are:
Perform water picking every macro-cycle.
By default, water picking starts after a half of macro-cycles is done:
% phenix.refine data.hkl model.pdb ordered_solvent=true \ ordered_solvent.mode=every_macro_cycle
Remove water only (based on specified criteria):
% phenix.refine data.hkl model.pdb ordered_solvent=true \ ordered_solvent.mode=filter_only
The following run illustrates the use of some important parameters:
% phenix.refine data.hkl model.pdb ordered_solvent=true solvent.params
where the parameter file solvent.params contains:
refinement { ordered_solvent { low_resolution = 2.8 b_iso_min = 1 b_iso_max = 50 b_iso = 25.0 occupancy_min = 1 occupancy_max = 1 occupancy = 1 primary_map_type = "m*Fobs-D*Fmodel" primary_map_cutoff = 3 min_solv_macromol_dist = 1.8 max_solv_macromol_dist = 6 min_solv_solv_dist = 1.8 } }This will skip water picking if the resolution of data is lower than 2.8A, it will remove waters with B < 1.0 or B > 50.0 A**2 or occupancy different from 1 or peak height at m*Fobs-D*Fmodel map lower then 3 sigma. It will not select or will remove existing water if water-water or water-macromolecule distance is less than 1.8A or water-macromolecule distance is greater than 6.0 A. The initial occupancies and B-factors of newly placed waters will be 1.0 and 25.0 correspondingly. If b_iso = None, then b_iso will be the mean atomic B-factor.
Hydrogens in refinement
phenix.refine offers two possibilities for handling of hydrogen atoms:
- riding model;
- complete refinement of H (H atoms will be refined as other atoms in the model)
Although the contribution of hydrogen atoms to X-ray scattering is weak (at high resolution) or negligible (at lower resolutions), the H atoms still present in real structures irrespective the data quality. Including them as riding model makes other model atoms aware of their positions and hence preventing non-physical (bad) contacts at no cost in terms of refinable parameters (= no risk of overfitting).
At subatomic resolution (approx. < 1.0 A) X-ray refinement or refinement using neutron data the parameters of H atoms may be refined as for other heavier atoms.
Below are some useful commands:
To add hydrogens to a model one need to run the Reduce program:
% phenix.reduce model.pdb > model_h_added.pdb
Once hydrogens added to a model, by default they will be refined as riding model:
% phenix.refine model.pdb data.hkl
When riding model is used, there are two options for hydrogens' ADP refinement: one isotropic B per whole molecule or one isotropic B per residue. The first option is the default and is probably more suited at resolutions lower than approx. 1.5 - 1.7 A. At higher resolution, better than approx. 1.5 A one may consider to switch to refinement of one B per residue:
% phenix.refine model.pdb data.hkl hydrogens.refine=one_b_per_residue
To switch back to refinement of one B per molecule:
% phenix.refine model.pdb data.hkl hydrogens.refine=one_b_per_molecule
To refine individual coordinates and ADP of H atoms:
% phenix.refine model.pdb data.hkl hydrogens.mode=full
Note that refine = one_b_per_residue *one_b_per_molecule keyword is ignored when hydrogens.mode=full is used.
To remove hydrogens from a model:
% phenix.pdbtools model.py remove="element H"
We strongly encourage to not remove hydrogen atoms after refinement since it will make the refinement statistics (R-factors, etc...) unreproducible without repeating exactly the same refinement protocol.
Refinement using twinned data
phenix.refine can handle the refinement of hemihedrally twinned data (two twin domains). Least square twin refinement can be carried out using the following commands line instructions:
% phenix.refine data.hkl model.pdb twin_law="-k,-h,-l"
The twin law (in this case -k,-h,-l) can be obtained from phenix.xtriage. If more than a single twin law is possible for the given unit cell and space group, using phenix.twin_map_utils might give clues which twin law is the most likely candidate to be used in refinement.
Correcting maps for anisotropy might be useful:
% phenix.refine data.hkl model.pdb twin_law="-k,-h,-l" \ detwin.map_types.aniso_correct=true
The detwinning mode is auto by default: it will perform algebraic detwinning for twin fraction below 40%, and detwinning using proportionality rules (SHELXL style) for fractions above 40%.
An important point to stress is that phenix.refine will only deal properly with twinning that involves two twin domains.
Neutron and joint X-ray and neutron refinement
Refinement using neutron data requires having H or/and D atoms added to the model. Use Reduce program to add all potential H atoms:
% phenix.reduce model.pdb > model_h.pdb
Currently, adding D atoms will require editing of model_h.pdb file to replace H with D where necessary.
Running refinement with neutron data only:
% phenix.refine data.hkl model.pdb scattering_table=neutron
this will tell phenix.refine that the data in data.hkl file is coming from neutron scattering experiment and the appropriate scattering factors will be used in all calculations. All the examples and phenix.refine functionality presented in this document are valid and compatible with using neutron data.
Using X-ray and neutron data simultaneously (joint X/N refinement).
phenix.refine allows simultaneous use of both data sets, X-ray and neutron. The data sets are allowed to have different number of reflections and be collected at different resolutions.
The only requirement (that is not enforced by the program but is the user's responsibility) is that both data sets have to be collected at the same temperature from same crystals (or grown in identical conditions, having identical space groups and unit cell parameters).
phenix.refine model.pdb data_xray.hkl neutron_data.file_name=data_neutron.hkl input.xray_data.labels=FOBSx input.neutron_data.labels=FOBSn
Examples of frequently used refinement protocols, common problems
Starting refinement from high R-factors:
% phenix.refine data.hkl model.pdb ordered_solvent=true main.number_of_macro_cycles=10 \ simulated_annealing=true strategy=rigid_body+individual_sites+individual_adp \
Depending on data resolution, refinement of individual ADP may be replaced with grouped B refinement:
% phenix.refine data.hkl model.pdb ordered_solvent=true simulated_annealing=true \ strategy=rigid_body+individual_sites+group_adp main.number_of_macro_cycles=10Adding TLS refinement may be a good idea. Note, unlike other programs, phenix.refine does not require "good model" for doing TLS refinement; TLS refinement is always stable in phenix.refine (please report if noticed otherwise):
% phenix.refine data.hkl model.pdb ordered_solvent=true simulated_annealing=true \ strategy=rigid_body+individual_sites+individual_adp+tls main.number_of_macro_cycles=10If NCS is present - once can use it:
% phenix.refine data.hkl model.pdb ordered_solvent=true simulated_annealing=true \ strategy=rigid_body+individual_sites+individual_adp+tls main.ncs=true \ main.number_of_macro_cycles=10 tls_group_selections.params \ rigid_body_selections.paramswhere tls_groups_selections.txt, rigid_body_groups_selections.txt are the files TLS and rigid body groups selections, NCS will be determined automatically from input PDB file. See this document for details on how specify these selections.
Note: in these four examples above we re-defined the default number of refinement macro-cycles from 3 to 10, since a start model with high R-factors most likely requires more cycles to become a good one. Also in these examples, the rigid body refinement will be run only once at first macro-cycle, the water picking will start after half of macro-cycles is done (after 5th), the SA will be done only twice - the first and before the last macro-cycles. Even though it is requested, the water picking may not be performed if the resolution is too low. All these default behaviors can be changed: see parameter's help for more details.
The last command looks too long to type it in the command line. Look this document for an example of how to make it like this:
% phenix.refine data.hkl model.pdb custom_par_1.params
- Refinement at "higher than medium" resolution - getting anisotropic.
Refining at higher resolution one may consider:
- At resolutions around 1.8 ... 1.7 A or higher it is a good idea to try refinement of anisotropic ADP for atoms at well ordered parts of the model. Well ordered parts can be identified by relatively small isotropic B-factors ~5-20A**2 of so.
- The riding model for H atoms should be used.
- Loosing stereochemistry and ADP restraints.
- Re-thing using the NCS (if present): it may turn out to be enough of data to not use NCS restrains. Try both, with and without NCS, and based on R-free vales decide the strategy.
Supposing the H atoms were added to the model, below is an example of what may want to do at higher resolution:
% phenix.refine data.hkl model.pdb adp.individual.anisotropic="resid 1-2 and not element H" \ adp.individual.isotropic="not (resid 1-2 and not element H)" wxc_scale=2 wxu_scale=2In the command above phenix.refine will refine the ADP of atoms in residues from 1 to 2 as anisotropic, the rest (including all H atoms) will be isotropic, the X-ray target contribution is increased for both, coordinate and ADP refinement. IMPORTANT: Please make note of the selection used in the above command: selecting atoms in residues 1 and 2 to be refined as anisotropic, one need to exclude hydrogens, which should be refined as isotropic.
Stereochemistry looks too tightly / loosely restrained, or gap between R-free and R-work seems too big: playing with restraints contribution.
Although the automatic calculation of weight between X-ray and stereochemistry or ADP restraint targets is good for most of cases, it may happen that rmsd deviations from ideal bonds length or angles are looking too tight or loose ( depending on resolution). Or the difference between R-work and R-free is too big (significantly bigger than approx. 5%). In such cases one definitely need to try loose or tighten the restraints. Hers is how for coordinates refinement:
% phenix.refine data.hkl model.pdb wxc_scale=5
The default value for wxc_scale is 0.5. Increasing wxc_scale will make the X-ray target contribution greater and restraints looser. Note: wxc_scale=0 will completely exclude the experimental data from the refinement resulting in idealization of the stereochemistry. For stereochemistry idealization use the separate command:
% phenix.geometry_minimization model.pdb
% phenix.geometry_minimization --help
To play with ADP restraints contribution:
% phenix.refine data.hkl model.pdb wxu_scale=3
The default value for wxu_scale is 1.0. Increasing wxu_scale will make the X-ray target contribution greater and therefore the B-factors restraints weaker.
Also, one can completely ignore the automatically determined weights (for both, coordinates and ADP refinement) and use specific values instead:
% phenix.refine data.hkl model.pdb fix_wxc=15.0
The refinement target will be: Etotal = 15.0 * Exray + Egeom
% phenix.refine data.hkl model.pdb fix_wxu=25.0
Having unknown to phenix.refine item in PDB file (novel ligand, etc...).
phenix.refine uses the CCP4 Monomer Library as the source of stereochemical information for building geometry restraints and reposting statistics.
If phenix.refine is unable to match an item in input PDB file against the Monomer Library it will stop with "Sorry" message explaining what to do and listing the problem atoms. If this happened, it is necessary to obtain a cif file (parameter file, describing unknown molecule) by either making it manually or having eLBOW program to generate it:
elbow.builder model.pdb --do-all --output=all_ligands
this will ask eLBOW to inspect the model_new.pdb file, find all unknown items in it and create one cif file for them all_ligands.cif. Alternatively, one can specify a three-letters name for the unknown residue:
elbow.builder model.pdb --residue=MAN --output=man
Once the cif file is created, the new run of phenix.refine will be:
phenix.refine model.pdb data.pdb man.cif
Useful options
Changing the number of refinement cycles and minimizer iterations
% phenix.refine data.hkl model.pdb main.number_of_macro_cycles=5 \ main.max_number_of_iterations=20
Creating R-free flags (if not present in the input reflection files)
% phenix.refine data.hkl model.pdb main.generate_r_free_flags=True
It is important to understand that reflections selected for test set must be never used in any refinement of any parameters. If the newly selected test reflections were used in refinement before then the corresponding R-free statistics will be wrong. In such case "refinement memory" removal procedure must be applied to recover proper statistics.
To change the default maximal number of test flags to be generated and the fraction:
% phenix.refine data.hkl model.pdb main.generate_r_free_flags=True \ r_free_flags.fraction=0.05 r_free_flags.max_free=500
Specify the name for output files
% phenix.refine data.hkl model.pdb output.prefix=lysozyme
Reflection output
At the end of refinement a file with Fobs, Fmodel, Fcalc, Fmask, FOM, R-free_flags can be written out (in MTZ format):
% phenix.refine data.hkl model.pdb export_final_f_model=mtz
To output the reflections in CNS reflection file format:
% phenix.refine data.hkl model.pdb export_final_f_model=cns
Note: Fmodel is the total model structure factor including all scales:
Fmodel = scale_k1 * exp(-h*U_overall*ht) * (Fcalc + k_sol * exp(-B_sol*s^2) * Fmask)
Setting the resolution range for the refinement
% phenix.refine data.hkl model.pdb main.low_resolution=15.0 main.high_resolution=2.0
Bulk solvent correction and anisotropic scaling
By default phenix.refine always starts with bulk solvent modeling and anisotropic scaling. Here is the list of command that may be of use in some cases:
Perform bulk-solvent modeling and anisotropic scaling only:
% phenix.refine data.hkl model.pdb strategy=none
Bulk-solvent modeling only (no anisotropic scaling):
% phenix.refine data.hkl model.pdb strategy=none bulk_solvent_and_scale.anisotropic_scaling=false
Anisotropic scaling only (no bulk-solvent modeling):
% phenix.refine data.hkl model.pdb strategy=none bulk_solvent_and_scale.bulk_solvent=false
Turn off bulk-solvent modeling and anisotropic scaling:
% phenix.refine data.hkl model.pdb main.bulk_solvent_and_scale=false
Fixing bulk-solvent and anisotropic scale parameters to user defined values:
% phenix.refine data.hkl model.pdb bulk_solvent_and_scale.params
where bulk_solvent_and_scale.params is the file containing these lines:
refinement { bulk_solvent_and_scale { k_sol_b_sol_grid_search = False minimization_k_sol_b_sol = False minimization_b_cart = False fix_k_sol = 0.45 fix_b_sol = 56.0 fix_b_cart { u11 = 1.2 u22 = 2.3 u33 = 3.6 u12 = 0.0 u13 = 0.0 u23 = 0.0 } } }Mask parameters:
Bulk solvent modeling involves the mask calculation. There are three principal parameters controlling it: solvent_radius, shrink_truncation_radius and grid_step_factor. Normally, these parameters are not supposed to be changed but can be changed:
% phenix.refine data.hkl model.pdb solvent_radius=1.0 \ shrink_truncation_radius=1.0 grid_step_factor=3
If one wants to gain some more drop in R-factors (somewhere between 0.0 and 1.0%) it is possible to run fairly time consuming (depending on structure size and resolution) procedure of mask parameters optimization:
% phenix.refine data.hkl model.pdb optimize_mask=true
This will perform the grid search for solvent_radius and shrink_truncation_radius and select the values giving the best R-factor.
By default phenix.refine adds isotropic component of overall anisotropic scale matrix to atomic B-factors, leaving the trace of overall anisotropic scale matrix equals to zero. This is the reason why one can observe the ADP changed even though the only anisotropic scaling was done and no ADP refinement performed.
Default refinement with user specified X-ray target function
Refinement with least-squares target:
% phenix.refine data.hkl model.pdb main.target=ls
Refinement with maximum-likelihood target (default):
% phenix.refine data.hkl model.pdb main.target=ml
Refinement with phased maximum-likelihood target:
% phenix.refine data.hkl model.pdb main.target=mlhl
If phenix.refine finds Hendrickson-Lattman coefficients in input reflection file, it will automatically switch to mlhl target. To disable this:
% phenix.refine data.hkl model.pdb main.use_experimental_phases=false
Modifying the initial model before refinement starts
phenix.refine offers several options to modify input model before refinement starts:
shaking of coordinates (adding a random shift to coordinates):
% phenix.refine data.hkl model.pdb sites.shake=0.3
rotation-translation shift of coordinates:
% phenix.refine data.hkl model.pdb sites.rotate="1 2 3" sites.translate="4 5 6"
shaking of occupancies:
% phenix.refine data.hkl model.pdb occupancies.randomize=true
shaking of ADP:
% phenix.refine data.hkl model.pdb adp.randomize=true
shifting of ADP (adding a constant value):
% phenix.refine data.hkl model.pdb adp.shift_b_iso=10.0
scaling of ADP (multiplying by a constant value):
% phenix.refine data.hkl model.pdb adp.scale_adp=0.5
setting a value to ADP:
% phenix.refine data.hkl model.pdb adp.set_b_iso=25
converting to isotropic:
% phenix.refine data.hkl model.pdb adp.convert_to_isotropic=true
converting to anisotropic:
% phenix.refine data.hkl model.pdb adp.convert_to_anisotropic=true \ modify_start_model.selection="not element H"
When converting atoms into anisotropic, it is important to make sure that hydrogens (if present in the model) are not converted into anisotropic.
By default, the specified manipulations will be applied to all atoms. However, it is possible to apply them to only selected atoms:
% phenix.refine data.hkl model.pdb adp.set_b_iso=25 modify_start_model.selection="chain A"
To write out the modified model (without any refinement), add: main.number_of_macro_cycles=0, e.g.:
% phenix.refine data.hkl model.pdb adp.set_b_iso=25 \ main.number_of_macro_cycles=0
All the commands listed above plus some more are available from phenix.pdbtools utility which in fact is used internally in phenix.refine to perform these manipulations. For more information on phenix.pdbtools type:
% phenix.pdbtools --help
Documentation on phenix.pdbtools is also available.
Refinement using FFT or direct structure factor calculation algorithm
% phenix.refine data.hkl model.pdb \ structure_factors_and_gradients_accuracy.algorithm=fft
% phenix.refine data.hkl model.pdb \ structure_factors_and_gradients_accuracy.algorithm=direct
Ignoring test (free) flags in refinement
Sometimes one need to use all reflections ("work" and "test") in the refinement; for example, at very low resolution where each single reflection counts, or at subatomic resolution where the risk of overfitting is very low. In the example below all the reflections are used in the refinement:
% phenix.refine data.hkl model.pdb ignore_r_free_flags=true
Note: 1) the corresponding statistics (R-factors, ...) will be identical for "work" and "test" sets; 2) it is still necessary to have test flags presented in input reflection file (or automatically generated by phenix.refine).
Using phenix.refine to calculate structure factors
The total structure factor used in phenix.refine nearly in all calculations is defined as:
Fmodel = scale_k1 * exp(-h*U_overall*ht) * (Fcalc + k_sol * exp(-B_sol*s^2) * Fmask)
Calculate Fcalc from atomic model and output in MTZ file (no solvent modeling or scaling):
% phenix.refine data.hkl model.pdb main.number_of_macro_cycles=0 \ main.bulk_solvent_and_scale=false export_final_f_model=mtz
Calculate Fcalc from atomic model including bulk solvent and all scales:
% phenix.refine data.hkl model.pdb main.number_of_macro_cycles=1 \ strategy=none export_final_f_model=mtz
To output CNS/Xplor formatted reflection file:
% phenix.refine data.hkl model.pdb main.number_of_macro_cycles=1 \ strategy=none export_final_f_model=cns
Resolution limits can be applied:
% phenix.refine data.hkl model.pdb main.number_of_macro_cycles=1 \ main.low_resolution=15.0 main.high_resolution=2.0
- The number of calculated structure factors will the same as the number of observed data (Fobs) provided in the input reflection files or less since resolution and sigma cutoffs may be applied to Fobs or some Fobs may be automatically removed by outliers detection procedure.
- The set of calculated structure factors has the same completeness as the set of provided Fobs.
Scattering factors
There are four choices for the scattering table to be used in phenix.refine:
- wk1995: Waasmaier & Kirfel table;
- it1992: International Crystallographic Tables (1992)
- n_gaussian: dynamic n-gaussian approximation
- neutron: table for neutron scattering
The default is n_gaussian. To switch to different table:
% phenix.refine data.hkl model.pdb scattering_table=neutron
Suppressing the output of certain files
The following command will tell phenix,refine to not write .eff, .geo, .def, maps and map coefficients files:
% phenix.refine data.hkl model.pdb write_eff_file=false write_geo_file=false \ write_def_file=false write_maps=false write_map_coefficients=false
The only output will be: .log and .pdb files.
Random seed
% phenix.refine data.hkl model.pdb random_seed=7112384
The results of certain refinement protocols, such as restrained refinement of coordinates (with SA or LBFGS minimization), are sensitive to the random seed. This is because: 1) for SA the refinement starts with random assignment of velocities to atoms; 2) the X-ray/geometry target weight calculation involves model shaking with some Cartesian dynamics. As result, running such refinement jobs with exactly the same parameters but different random seeds will produce different refinement statistics. The author's experience includes the case where the difference in R-factors was about 2.0% between two SA runs.
Also, this opens a possibility to perform multi-start SA refinement to create an ensemble of slightly different models in average but sometimes containing significant variations in certain parts.
Electron density maps
phenix.refine can compute and output three types of maps: k*Fobs-n*Fmodel, 2m*Fobs-D*Fmodel and m*Fobs-D*Fmodel, where k and n are scalar parameters. The result is output either as in ASCII X-PLOR format files. A reflection file with map coefficients is also generated for use in Coot or XtalView. The example below illustrates the main options:
% phenix.refine data.hkl model.pdb map.params
refinement {
electron_density_map {
map_types = *k*Fobs-n*Fmodel *2m*Fobs-D*Fmodel *m*Fobs-D*Fmodel
k = 1
n = 1
grid_resolution_factor = 1/4.
region = *selection cell
atom_selection = name CA or name N or name C
apply_sigma_scaling = False
apply_volume_scaling = True
}
}
This will output three map files containing Fobs-Fmodel, 2m*Fobs-D*Fmodel and m*Fobs-D*Fmodel maps (which is requested by putting * in front of corresponding map names). All maps will be in absolute scale (in e/A**3). The map finess will be (data resolution)*grid_resolution_factor and the map will be output around main chain atoms. If atom_selection is set to None or all then map will be computed for all atoms.
Calculating model map
The most direct and logical way is to calculate it using the standard formulas rho(r)=... . However, this option is currently not available in phenix.refine. A work-around is to compute (Fcalc, phi_calc) to certain resolution and completeness first and then do the Fourier transformation. This will result in Fourier image of the "true" electron density ("true" = calculated by formulas) at given resolution and completeness. As higher resolution and completeness of Fcalc, as closer this Fourier image to the "true" density. This is possible to do with phenix.refine and the following command will do this:
% phenix.refine data.hkl model.pdb main.number_of_macro_cycles=0 \ electron_density_map.map_types="k*Fobs-n*Fmodel" electron_density_map.k=0 \ electron_density_map.n=-1 main.bulk_solvent_and_scale=false strategy=none
In the example above we load the model and data into phenix.refine and ask it to do nothing (main.number_of_macro_cycles=0, strategy=none) but calculate the k*Fobs-n*Fmodel map with the coefficients k=0 and n=-1. Here Fmodel is just Fcalc from atomic model and does not include any bulk solvent contribution or other scales (main.bulk_solvent_and_scale=false).
Please note that the Fourier image calculated in this example will be based on the resolution and completeness of provided Fobs (data.mtz) and will not be exactly what one can get with formulas rho(r)=...
Refining with anomalous data (or what phenix.refine does with Fobs+ and Fobs-).
The way phenix.refine uses Fobs+ and Fobs- is controlled by main.force_anomalous_flag_to_be_equal_to parameter.
Default behavior: phenix.refine will use all Fobs: Fobs+ and Fobs- as independent reflections:
% phenix.refine model.pdb data_anom.hkl
phenix.refine will generate missing Bijvoet mates and use all Fobs+ and Fobs- as independent reflections if:
% phenix.refine model.pdb data_anom.hkl force_anomalous_flag_to_be_equal_to=true
phenix.refine will merge Fobs+ and Fobs-, that is instead of two separate Fobs+ and Fobs- it will use one value F_mean = (Fobs+ + Fobs-)/2 if:
% phenix.refine model.pdb data_anom.hkl force_anomalous_flag_to_be_equal_to=false
Look this documentation to see how to use and refine f' and f''.
Rejecting reflections by sigma
Reflections can be rejected by sigma cutoff criterion applied to amplitudes Fobs <= sigma_fobs_rejection_criterion * sigma(Fobs):
% phenix.refine model.pdb data_anom.hkl sigma_fobs_rejection_criterion=2
or/and intensities Iobs <= sigma_iobs_rejection_criterion * sigma(Iobs):
% phenix.refine model.pdb data_anom.hkl sigma_iobs_rejection_criterion=2
Internally, phenix.refine uses amplitudes. If both sigma_fobs_rejection_criterion and sigma_iobs_rejection_criterion are given as non-zero values, then both criteria will be applied: first to Iobs, then to Fobs (after cutted Iobs got converted to Fobs):
% phenix.refine model.pdb data_anom.hkl sigma_fobs_rejection_criterion=2 \ sigma_iobs_rejection_criterion=2
By default, both sigma_fobs_rejection_criterion and sigma_iobs_rejection_criterion are set to zero (no reflections rejected) and, unless strongly motivated, we encourage to not change these values. If amplitudes provided at input then sigma_fobs_rejection_criterion is ignored.
Developer's tools
phenix.refine offers a broad functionality for experimenting that may not be useful in everyday practice but handy for testing ideas.
Substitute input Fobs with calculated Fcalc, shake model and refine it
Instead of using Fobs from input data file one can ask phenix.refine to use the calculated structure factors Fcalc using the input model. Obviously, the R-factors will be zero throughout the refinement. One can also shake various model parameters (see this document for details), then refinement will start with some bad statistics (big R-factors at least) and hopefully will converge to unmodified start model (if not shaken too well).
Also it's possible to simulate Flat bulk solvent model contribution and anisotropic scaling:
% phenix.refine model.pdb data.hkl experiment.paramswhere experiment.params contains the following:
refinement { main { fake_f_obs = True } modify_start_model { selection = "chain A" sites { shake = 0.5 } } fake_f_obs { k_sol = 0.35 b_sol = 45.0 b_cart = 1.25 3.78 1.25 0.0 0.0 0.0 scale = 358.0 } }In this example, the input Fobs will be substituted with the same amount of Fcalc (absolute values of Fcalc), then the coordinates of the structure will be shaken to achieve rmsd=0.5 and finally the default run of refinement will be done. The bulk solvent and anisotropic scale and overall scalar scales are also added to thus obtained Fcalc in accordance with Fmodel definition (see this document for definition of total structure factor, Fmodel). Expected refinement behavior: R-factors will drop from something big to zero.
CIF modifications and links
phenix.refine uses the CCP4 monomer library to build geometry restraints (bond, angle, dihedral, chirality and planarity restraints). The CCP4 monomer library comes with a set of "modifications" and "links" which are defined in the file mon_lib_list.cif. Some of these are used automatically when phenix.refine builds the geometry restraints (e.g. the peptide and RNA/DNA chain links). Other links and modifications have to be applied manually, e.g. (cif_modification.params file):
refinement.pdb_interpretation.apply_cif_modification {
data_mod = 5pho
residue_selection = resname GUA and name O5T
}
Here a custom 5pho modification is applied to all GUA residues with an O5T atom. I.e. the modification can be applied to multiple residues with a single apply_cif_modification block. The CIF modification is supplied as a separate file on the phenix.refine command line, e.g. (data_mod_5pho.cif file):
data_mod_5pho # loop_ _chem_mod_atom.mod_id _chem_mod_atom.function _chem_mod_atom.atom_id _chem_mod_atom.new_atom_id _chem_mod_atom.new_type_symbol _chem_mod_atom.new_type_energy _chem_mod_atom.new_partial_charge 5pho add . O5T O OH . loop_ _chem_mod_bond.mod_id _chem_mod_bond.function _chem_mod_bond.atom_id_1 _chem_mod_bond.atom_id_2 _chem_mod_bond.new_type _chem_mod_bond.new_value_dist _chem_mod_bond.new_value_dist_esd 5pho add O5T P coval 1.520 0.020
% phenix.refine model_o5t.pdb data.hkl data_mod_5pho.cif cif_modification.params
Similarly, a link can be applied like this (cif_link.params file):
refinement.pdb_interpretation.apply_cif_link {
data_link = MAN-THR
residue_selection_1 = chain X and resname MAN and resid 900
residue_selection_2 = chain X and resname THR and resid 42
}
% phenix.refine model.pdb data.hkl cif_link.params
The residue selections for links must select exactly one residue each. The MAN-THR link is pre-defined in mon_lib_list.cif. Custom links can be supplied as additional files on the phenix.refine command line. See mon_lib_list.cif for examples. The full path to this file can be obtained with the command:
% phenix.where_mon_lib_list_cif
All apply_cif_modification and apply_cif_link definitions will be included into the .def files. I.e. it is not necessary to specify the definitions again if further refinement runs are started with .def files.
Note that all LINK, SSBOND, HYDBND, SLTBRG and CISPEP records in the input PDB files are ignored.
Definition of custom bonds and angles
Most geometry restraints (bonds, angles, etc.) are generated automatically based on the CCP4 monomer library. Additional custom bond and angle restraints, e.g. between protein and a ligand or ion, can be specified in this way:
refinement.geometry_restraints.edits {
zn_selection = chain X and resname ZN and resid 200 and name ZN
his117_selection = chain X and resname HIS and resid 117 and name NE2
asp130_selection = chain X and resname ASP and resid 130 and name OD1
bond {
action = *add
atom_selection_1 = $zn_selection
atom_selection_2 = $his117_selection
distance_ideal = 2.1
sigma = 0.02
}
bond {
action = *add
atom_selection_1 = $zn_selection
atom_selection_2 = $asp130_selection
distance_ideal = 2.1
sigma = 0.02
}
angle {
action = *add
atom_selection_1 = $his117_selection
atom_selection_2 = $zn_selection
atom_selection_3 = $asp130_selection
angle_ideal = 109.47
sigma = 5
}
}
Placing the above parameters into file restraints_edits.params, one can run:
% phenix.refine model.pdb data.hkl restraints_edits.params
The atom selections must uniquely select a single atom. Save the geometry_restraints.edits to a file and specify the file name as an additional argument when running phenix.refine for the first time. The edits will be included into the .def files. I.e. it is not necessary to manually specify them again if further refinement runs are started with .def files.
Atom selection examples
all
All C-alpha atoms (not case sensitive):
name ca
All atoms with ``H`` in the name (``*`` is a wildcard character):
name *H*
Atoms names with ``*`` (backslash disables wildcard function):
name o2\*
name 'O 1'
Atom names with primes don't necessarily have to be quoted:
name o2'
Boolean ``and``, ``or`` and ``not``:
resname ALA and (name ca or name c or name n or name o) chain a and not altid b resid 120 and icode c and model 2 segid a and element c and charge 2+ and anisou
resseq 188
resid is a synonym for resseq:
resid 188
Note that if there are several chains containing residue number 188, all of them will be selected. To be more specific and select residue 188 in particular chain:
chain A and resid 188
this will select residue 188 only in chain A.
All residues from 188 to the end (including 188):
resseq 188:
resseq 188-
All residues from the beginning to 188 (including 188):
resseq :188 resseq -188
Residues 2 through 10 (including 2 and 10):
resseq 2:10 resseq 2-10
resname ALA and backbone resname ALA and sidechain peptide backbone rna backbone or dna backbone water or nucleotide dna and not (phosphate or ribose) within(5, (nucleotide or peptide) backbone)
Referencing phenix.refine
Afonine, P.V., Grosse-Kunstleve, R.W. & Adams, P.D. (2005). CCP4 Newsl. 42, contribution 8.
Relevant reading
Below is the list of papers either published in connection with phenix.refine or used to implement specific features in phenix.refine:
- Maximum-likelihood in structure refinement:
- V.Yu., Lunin & T.P., Skovoroda. Acta Cryst. (1995). A51, 880-887. "R-free likelihood-based estimates of errors for phases calculated from atomic models"
- Pannu, N.S., Murshudov, G.N., Dodson, E.J. & Read, R.J. (1998). Acta Cryst. D54, 1285-1294. "Incorporation of Prior Phase Information Strengthens Maximum-Likelihood Structure Refinement"
- V.Y., Lunin, P.V. Afonine & A.G., Urzhumtsev. Acta Cryst. (2002). A58, 270-282. "Likelihood-based refinement. I. Irremovable model errors"
- P. Afonine, V.Y. Lunin & A. Urzhumtsev. J. Appl. Cryst. (2003). 36, 158-159. "MLMF: least-squares approximation of likelihood-based refinement criteria"
- ADP:
- V. Schomaker & K.N. Trueblood. Acta Cryst. (1968). B24, 63-76. "On the rigid-body motion of molecules in crystals"
- F.L. Hirshfeld. Acta Cryst. (1976). A32, 239-244. "Can X-ray data distinguish bonding effects from vibrational smearing?"
- T.R. Schneider. Proceedings of the CCP4 Study Weekend (E. Dodson, M. Moore, A. Ralph, and S. Bailey, eds.), SERC Daresbury Laboratory, Daresbury, U.K., pp. 133-144 (1996). "What can we Learn from Anisotropic Temperature Factors ?"
- M.D. Winn, M.N. Isupov & G.N. Murshudov. Acta Cryst. (2001). D57, 122-133. "Use of TLS parameters to model anisotropic displacements in macromolecular refinement"
- R.W. Grosse-Kunstleve & P.D. Adams. J. Appl. Cryst. (2002). 35, 477-480. "On the handling of atomic anisotropic displacement parameters"
- P. Afonine & A. Urzhumtsev. (2007). CCP4 Newsletter on Protein Crystallography. 45. Contribution 6. "On determination of T matrix in TLS modeling"
- Rigid body refinement:
- Afonine PV, Grosse-Kunstleve RW, Adams PD & Urzhumtsev AG. "Methods for optimal rigid body refinement of models with large displacements". (in preparation for Acta Cryst. D).
- Bulk-solvent modeling and anisotropic scaling:
- S. Sheriff & W.A. Hendrickson. Acta Cryst. (1987). A43, 118-121. "Description of overall anisotropy in diffraction from macromolecular crystals"
- Jiang, J.-S. & Brünger, A. T. (1994). J. Mol. Biol. 243, 100-115. "Protein hydration observed by X-ray diffraction. Solvation properties of penicillopepsin and neuraminidase crystal structures."
- A. Fokine & A. Urzhumtsev. Acta Cryst. (2002). D58, 1387-1392. "Flat bulk-solvent model: obtaining optimal parameters"
- P.V. Afonine, R.W. Grosse-Kunstleve & P.D. Adams. Acta Cryst. (2005). D61, 850-855. "A robust bulk-solvent correction and anisotropic scaling procedure"
- Refinement at subatomic resolution:
- Afonine, P.V., Pichon-Pesme, V., Muzet, N., Jelsch, C., Lecomte, C. & Urzhumtsev, A. (2002). CCP4 Newsletter on Protein Crystallography. 41. "Modeling of bond electron density"
- Afonine P.V., Lunin, V., Muzet, N. & Urzhumtsev, A. (2004). Acta Cryst., D60, 260-274. "On the possibility of observation of valence electron density for individual bonds in proteins in conventional difference maps"
- P.V. Afonine, R.W. Grosse-Kunstleve, P.D. Adams, V.Y. Lunin, A. Urzhumtsev. "On macromolecular refinement at subatomic resolution with interatomic scatterers" (submitted to Acta Cryst. D).
- LBFGS minimization:
- Liu, D.C. & Nocedal, J. (1989). Mathematical Programming, 45, 503-528. "On the limited memory BFGS method for large scale optimization"
- Dynamics, simulated annealing:
- Brünger, A.T., Kuriyan, J., Karplus, M. (1987). Science. 235, 458-460. "Crystallographic R factor refinement by molecular dynamics"
- Adams, P.D., Pannu, N.S., Read, R.J. & Brünger, A.T. (1997). Proc. Natl. Acad. Sci. 94, 5018-5023. "Cross-validated maximum likelihood enhances crystallographic simulated annealing refinement"
- L.M. Rice, Y. Shamoo & A.T. Brünger. J. Appl. Cryst. (1998). 31, 798-805. "Phase Improvement by Multi-Start Simulated Annealing Refinement and Structure-Factor Averaging"
- Brünger, A.T & Adams, P.D. (2002). Acc. Chem. Res. 35, 404-412. "Molecular dynamics applied to X-ray structure refinement"
- Target weights calculation:
- Brünger, A.T., Karplus, M. & Petsko, G.A. (1989). Acta Cryst. A45, 50-61. "Crystallographic refinement by simulated annealing: application to crambin"
- Brünger, A.T. (1992). Nature (London), 355, 472-474. "The free R value: a novel statistical quantity for assessing the accuracy of crystal structures"
- Adams, P.D., Pannu, N.S., Read, R.J. & Brünger, A.T. (1997). Proc. Natl. Acad. Sci. 94, 5018-5023. "Cross-validated maximum likelihood enhances crystallographic simulated annealing refinement"
- Electron density maps (Fourier syntheses) calculation:
- A.G. Urzhumtsev, T.P. Skovoroda & V.Y. Lunin. J. Appl. Cryst. (1996). 29, 741-744. "A procedure compatible with X-PLOR for the calculation of electron-density maps weighted using an R-free-likelihood approach"
- Monomer Library:
- Vagin, A.A., Steiner, R.A., Lebedev, A.A, Potterton, L., McNicholas, S., Long, F. & Murshudov, G.N. (2004). Acta Cryst. D60, 2184-2195. "REFMAC5 dictionary: organization of prior chemical knowledge and guidelines for its use"
- Scattering factors:
- D. Waasmaier & A. Kirfel. Acta Cryst. (1995). A51, 416-431. "New analytical scattering-factor functions for free atoms and ions"
- International Tables for Crystallography (1992)
- Neutron News, Vol. 3, No. 3, 1992, pp. 29-37. http://www.ncnr.nist.gov/resources/n-lengths/list.html
- Grosse-Kunstleve RW, Sauter NK & Adams PD. Newsletter of the IUCr Commission on Crystallographic Computing 2004, 3:22-31. "cctbx news"
- Neutron and joint X-ray/neutron refinement:
- A. Wlodawer & W.A. Hendrickson. Acta Cryst. (1982). A38, 239-247. "A procedure for joint refinement of macromolecular structures with X-ray and neutron diffraction data from single crystals"
- A. Wlodawer, H. Savage & G. Dodson. Acta Cryst. (1989). B45, 99-107. "Structure of insulin: results of joint neutron and X-ray refinement"
- Stereochemical restraints:
- Grosse-Kunstleve, R.W., Afonine, P.V., Adams, P.D. (2004). Newsletter of the IUCr Commission on Crystallographic Computing, 4, 19-36. "cctbx news: Geometry restraints and other new features"
- Parameters parsing and interpretation:
- Grosse-Kunstleve RW, Afonine PV, Sauter NK, Adams PD. Newsletter of the IUCr Commission on Crystallographic Computing 2005, 5:69-91. "cctbx news: Phil and friends"
Questions, problems, bugs, more information
Send bug reports to: bugs@phenix-online.org
For help write to: help@phenix-online.org
Questions: phenixbb@phenix-online.org
More information: www.phenix-online.org or type:
% phenix.about
The latest version of this documentation: http://phenix-online.org/download/cci_apps/ -> click on Documentation link right next to phenix.refine
List of all 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
-------------------------------------------------------------------------------
refinement Scope of parameters for structure refinement with phenix.refine
crystal_symmetry Scope of space group and unit cell parameters
unit_cell= None
space_group= None
input Scope of input file names, labels, processing directions
symmetry_safety_check= *error warning Check for consistency of crystall
symmetry from model and data files
pdb
file_name= None Model file(s) name (PDB)
neutron_data Scope of neutron data
file_name= None
labels= None
neutron_r_free_flags Scope of r-free flags for neutron data
file_name= None Name of file containing free-R flags
label= None
test_flag_value= None
disable_suitability_test= False XXX
ignore_pdb_hexdigest= False If True, disables safety check based on
MD5 hexdigests stored in PDB files produced by
previous runs.
xray_data Scope of X-ray data
file_name= None
labels= None
r_free_flags Scope of r-free flags for X-ray data
file_name= None Name of file containing free-R flags
label= None
test_flag_value= None
disable_suitability_test= False XXX
ignore_pdb_hexdigest= False If True, disables safety check based on
MD5 hexdigests stored in PDB files produced by
previous runs.
experimental_phases Scope of experimental phase information (HL
coeeficients)
file_name= None
labels= None
monomers Scope of monomers information (CIF files)
file_name= None Monomer file(s) name (CIF)
output Scope for output files
prefix= None Prefix for all output files
serial= None Serial number for consequtive refinement runs
serial_format= "%03d" Format serial number in output file name
write_eff_file= True
write_geo_file= True
write_def_file= True
export_final_f_model= mtz cns Write Fobs, Fmodel, various scales and
more to MTZ or CNS file
write_maps= True
write_map_coefficients= True
electron_density_map Electron density maps calculation parameters
map_types= k*Fobs-n*Fmodel *2m*Fobs-D*Fmodel *m*Fobs-D*Fmodel
k= 2.0
n= 1.0
map_format= *xplor
map_coefficients_format= *mtz phs
grid_resolution_factor= 1/3
region= *selection cell
atom_selection= None
atom_selection_buffer= 3
apply_sigma_scaling= True
apply_volume_scaling= False
mtz_labels
map_type= 2m*Fobs-D*Fmodel
amplitudes= 2FOFCWT
phases= PH2FOFCWT
mtz_labels
map_type= m*Fobs-D*Fmodel
amplitudes= FOFCWT
phases= PHFOFCWT
mtz_labels
map_type= k*Fobs-n*Fmodel
amplitudes= oFOoFCWT
phases= oPHFOoFCWT
refine Scope of refinement flags (=flags defining what to refine) and atom
selections (=atoms to be refined)
strategy= *individual_sites rigid_body *individual_adp group_adp tls
individual_occupancies group_occupancies group_anomalous none
Atomic parameters to be refined
sites Scope of atom selections for coordinates refinement
individual= None Selections for individual atoms
rigid_body= None Selections for rigid groups
adp Scope of atom selections for ADP (Atomic Displacement Parameters)
refinement
group= None One isotropic ADP for group of selected here atoms will
be refined
one_adp_group_per_residue= True Refine one isotropic ADP per residue
tls= None Selection(s) for TLS group(s)
individual Scope of atom selections for refinement of individual ADP
isotropic= None Selections for atoms to be refinement with
isotropic ADP
anisotropic= None Selections for atoms to be refinement with
anisotropic ADP
occupancies Scope of atom selections for occupancy refinement
individual= None Selection(s) for indivudual atoms
group= None One occupancy per group of selected atoms will be refined
one_occupancy_group_per_residue= False Refine one occupancy per
residue
anomalous_scatterers
group
selection= None
f_prime= 0
f_double_prime= 0
refine= *f_prime *f_double_prime
main Scope for most common and frequently used parameters
high_resolution= None High resolution cutoff for the data to be used in
refinement
low_resolution= None Low resolution cutoff for the data to be used in
refinement
bulk_solvent_and_scale= True Do bulk solvent correction and anisotropic
scaling
simulated_annealing= False Do simulated annealing
ordered_solvent= False Add (or/and remove) and refine ordered solvent
molecules (water)
ncs= False Use restraints NCS in refinement (can be determined
automatically)
dbe= False Build and use IAS (interatomic scatterers) model (at
resolutions higher than approx. 0.9 A)
number_of_macro_cycles= 3 Number of macro-cycles to be performed
max_number_of_iterations= 25
generate_neutron_r_free_flags= False Generate R-free flags for neutron
dataset (if not available in input files)
generate_r_free_flags= False Generate R-free flags (if not available in
input files)
use_form_factor_weights= False
tan_u_iso= False Use tan() reparameterization in ADP refinement
(currently disabeled)
use_convergence_test= False Determine if refinement converged and stop
then
target= *ml mlhl ml_sad ls Choices for refinement target
min_number_of_test_set_reflections_for_max_likelihood_target= 50 minimum
number of
test
reflections
required
for use of
ML target
max_number_of_resolution_bins= 30
sigma_fobs_rejection_criterion= 0.0 Value for sigma cutoff for Fobs
sigma_iobs_rejection_criterion= 0.0 Value for sigma cutoff for Iobs
reference_xray_structure= None
use_experimental_phases= None Use experimental phases if available
force_anomalous_flag_to_be_equal_to= None
compute_optimal_errors= False
random_seed= 2679941 Ransom seed
scattering_table= wk1995 it1992 *n_gaussian neutron Choices of
scattering table for structure factors calculations
use_normalized_geometry_target= True
target_weights_only= False Calculate target weights only and exit
refinement
use_f_model_scaled= False Use Fmodel structure factors multiplied by
overall scale factor scale_k1
max_d_min= 0.25 Highest allowable resolution limit for refinement
fake_f_obs= False Substitute real experimental Fobs with those
calculated from input model (scales and solvent can be
added)
optimize_mask= False Refine mask parameters (solvent_radius and
shrink_truncation_radius)
occupancy_max= 1.0 Maximum allowable occupancy of an atom
occupancy_min= 0.0 Minimum allowable occupancy of an atom
stir= None Stepwise increase of resolution: start refinement at lower
resolution and gradually proceed with higher resolution
fft_vs_direct= False Check accuracy of approximations used in Fcalc
calculations
ignore_r_free_flags= False Use all reflections in refinement (work and
test)
rigid_bond_test= False Compute Hirshfeld's rigid bond test value (RBT)
use_xn_grads_filtering= False
modify_start_model Scope of parameters to modify initial model before
refinement
selection= None Selection for atoms to be modified
adp Scope of options to modify ADP of selected atoms
randomize= None Randomize ADP within a certain range
set_b_iso= None Set ADP of atoms to set_b_iso
convert_to_isotropic= None Convert atoms to isotropic
convert_to_anisotropic= None Convert atoms to anisotropic
shift_b_iso= None Add shift_b_iso value to ADP
scale_adp= None Multiply ADP by scale_adp
sites Scope of options to modify coordinates of selected atoms
shake= None Randomize coordinates with mean error value equal to shake
translate= 0 0 0 Translational shift
rotate= 0 0 0 Rotational shift
euler_angle_convention= *xyz zyz Euler angles convention to be used
for rotation
occupancies Scope of options to modify occupancies of selected atoms
randomize= None Randomize occupancies within a certain range
output Write out PDB file with modified model (file name is defined in
write_modified)
pdb
file_name= None
fake_f_obs Scope of parameters to simulate Fobs
k_sol= 0.0 Bulk solvent k_sol values
b_sol= 0.0 Bulk solvent b_sol values
b_cart= 0 0 0 0 0 0 Anisotropic scale matrix
scale= 1.0 Overall scale factor
hydrogens Scope of parameters for H atoms refinement
mode= full *riding Choice for refinement: riding model or full (H is
refined as other atoms; useful at very high resolutions only)
refine= one_b_per_residue *one_b_per_molecule Startegy for ADP
refinement of H atoms (used only if mode=riding)
fix_xh_distances= False Keep X-H distances unchanges during refinement
(H is hydrogen atom X is any atom bonded with H)
group_b_iso
number_of_macro_cycles= 3
max_number_of_iterations= 25
convergence_test= False
run_finite_differences_test= False
adp
iso
max_number_of_iterations= 25
automatic_randomization_if_all_equal= True
scaling
scale_max= 3.0
scale_min= 10.0
tls
one_residue_one_group= None
refine_T= True
refine_L= True
refine_S= True
number_of_macro_cycles= 2
max_number_of_iterations= 25
start_tls_value= None
run_finite_differences_test= False
eps= 1.e-6
adp_restraints
iso
use_u_local_only= False
sphere_radius= 5.0
distance_power= 1.69
average_power= 1.03
wilson_b_weight_auto= False
wilson_b_weight= None
plain_pairs_radius= 5.0
refine_ap_and_dp= False
b_iso_max= None
group_occupancy
number_of_macro_cycles= 3
max_number_of_iterations= 25
convergence_test= False
run_finite_differences_test= False
group_anomalous
number_of_minimizer_cycles= 3
lbfgs_max_iterations= 20
number_of_finite_difference_tests= 0
rigid_body Scope of parameters for rigid body refinement
protocol= one_zone *multiple_zones Choices for rigid body refinement
protocol
mode= *first_macro_cycle_only every_macro_cycle Defines how many times
perform rigid body refinement during refinement run:
first_macro_cycle_only - run only once at the first macrocycle;
every_macro_cycle - rigid body refinement is performed
main.number_of_macro_cycles times
target= ls_wunit_k1 *ml Rigid body refinement target function:
least-squares or maximum-likelihood
refine_rotation= True
refine_translation= True
min_number_of_reflections= 250 Number of reflections that defines the
first lowest resolution zone for
multiple_zones protocol
max_iterations= 25 Number of minimization iterations
bulk_solvent_and_scale= True Do bulk-solvent and scaling within rigid
body refinement
euler_angle_convention= *xyz zyz
high_resolution= 2.0 High resolution cutoff (used for rigid body
refinement only)
max_low_high_res_limit= 8.0 Maxumum value for high resolution cutoff for
the first lowest resolution zone
number_of_zones= 5 Number of resolution zones for MZ protocol
lbfgs_line_search_max_function_evaluations= 10
ncs
find_automatically= True
coordinate_sigma= None
b_factor_weight= None
excessive_distance_limit= 1.5
find_ncs
temp_dir= "" temporary directory (it must exist if you define it)
min_length= 10 minimum number of matching residues in a segment
njump= 1 Take every njumpth residue instead of each 1
njump_recursion= 10 Take every njump_recursion residue instead of
each 1 on recursive call
min_length_recursion= 50 minimum number of matching residues in a
segment for recursive call
min_percent= 95. min percent identity of matching residues
max_rmsd= 2. max rmsd of 2 chains. If 0, then only search for domains
quick= True If quick is set and all chains match, just look for 1 NCS
group
max_rmsd_user= 3. max rmsd of chains suggested by user (i.e., if
called from phenix.refine with suggested ncs groups)
verbose= False Verbose output
domain_finding_parameters
find_invariant_domains= True Find the parts of a set of chains
that follow NCS
initial_rms= 0.5 Guess of RMS among chains
match_radius= 2.0 Keep atoms that are within match_radius of
NCS-related atoms
similarity_threshold= 0.75 Threshold for similarity between
segments
smooth_length= 0 two segments separated by smooth_length or less
get connected
min_contig_length= 3 segments < min_contig_length rejected
min_fraction_domain= 0.2 domain must be this fraction of a chain
max_rmsd_domain= 2. max rmsd of domains
restraint_group
reference= None
selection= None
coordinate_sigma= 0.05
b_factor_weight= 10
pdb_interpretation
link_distance_cutoff= 3
disulfide_distance_cutoff= 3
chir_volume_esd= 0.2
nonbonded_distance_cutoff= None
default_vdw_distance= 1
min_vdw_distance= 1
nonbonded_buffer= 1
vdw_1_4_factor= 0.8
translate_cns_dna_rna_residue_names= None
apply_cif_modification
data_mod= None
residue_selection= None
apply_cif_link
data_link= None
residue_selection_1= None
residue_selection_2= None
peptide_link
cis_threshold= 45
discard_psi_phi= True
omega_esd_override_value= None
clash_guard
nonbonded_distance_threshold= 0.5
max_number_of_distances_below_threshold= 100
max_fraction_of_distances_below_threshold= 0.1
geometry_restraints
edits
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.
distance_ideal= None
sigma= None
angle
action= *add delete change
atom_selection_1= None
atom_selection_2= None
atom_selection_3= None
angle_ideal= None
sigma= None
geometry_restraints
remove
angles= None
dihedrals= None
chiralities= None
planarities= None
ordered_solvent
low_resolution= 2.8 Low resolution limit for water picking (at lower
resolution water will not be picked even if requessted)
mode= *auto filter_only every_macro_cycle Choices for water picking
strategy: auto - start water picking after ferst few macro-cycles,
filter_only - remove water only, every_macro_cycle - do water
update every macro-cycle
output_residue_name= HOH
output_chain_id= S
output_atom_name= O
b_iso_min= 1.0 Minimum B-factor value, waters with smaller value will be
rejected
b_iso_max= 50.0 Maximum B-factor value, waters with bigger value will be
rejected
b_iso= None Initial B-factor value for newly added water
scattering_type= O Defines scattering factors for newly added waters
occupancy_min= 0.1 Minimum occupancy value, waters with smaller value
will be rejected
occupancy_max= 1.2 Maximum occupancy value, waters with bigger value
will be rejected
occupancy= 1.0 Initial occupancy value for newly added water
bulk_solvent_mask_exclusions= True Do water selection based on
bulk-solvent mask
use_sigma_scaled_maps= True Use sigma scales maps for water pick picking
primary_map_type= m*Fobs-D*Fmodel
primary_map_k= None
primary_map_n= None
primary_map_cutoff= 3.0
secondary_map_type= 2m*Fobs-D*Fmodel
secondary_map_k= None
secondary_map_n= None
secondary_map_cutoff= 1.0
peak_map_matching_tolerance= 2.0
resolution_factor= 1./4.
min_solv_macromol_dist= 1.8
max_solv_macromol_dist= 6.0
min_solv_solv_dist= 1.8
max_number_of_peaks= None
verbose= 1
peak_search
peak_search_level= 1
max_peaks= 0
interpolate= True
min_distance_sym_equiv= 1.e-6
general_positions_only= False
min_cross_distance= 2.0
bulk_solvent_and_scale
bulk_solvent= True
anisotropic_scaling= True
statistical_solvent= False
k_sol_b_sol_grid_search= True
minimization_k_sol_b_sol= True
minimization_b_cart= True
target= ls_wunit_k1 *ml
symmetry_constraints_on_b_cart= True
k_sol_max= 0.6
k_sol_min= 0.0
b_sol_max= 150.0
b_sol_min= 10.0
k_sol_grid_search_max= 0.6
k_sol_grid_search_min= 0.0
b_sol_grid_search_max= 100.0
b_sol_grid_search_min= 10.0
k_sol_step= 0.05
b_sol_step= 5.0
number_of_macro_cycles= 3
number_of_minimization_macro_cycles= 3
number_of_cycles_for_anisotropic_scaling= 3
fix_k_sol= None
fix_b_sol= None
apply_back_trace_of_b_cart= False
start_minimization_from_k_sol= 0.35
start_minimization_from_b_sol= 46.0
nu_fix_n_atoms= None
nu_fix_b_atoms= None
verbose= -1
fix_b_cart
u11= None
u22= None
u33= None
u12= None
u13= None
u23= None
start_minimization_from_b_cart
u11= 0.0
u22= 0.0
u33= 0.0
u12= 0.0
u13= 0.0
u23= 0.0
alpha_beta
free_reflections_per_bin= 140
number_of_macromolecule_atoms_absent= 225
n_atoms_included= 0
bf_atoms_absent= 15.0
final_error= 0.0
absent_atom_type= "O"
method= *est calc
estimation_algorithm= *analytical iterative
verbose= -1
interpolation= True
fix_scale_for_calc_option= None
number_of_waters_absent= 613
sigmaa_estimator
kernel_width_free_reflections= 100
kernel_on_chebyshev_nodes= True
number_of_sampling_points= 20
number_of_chebyshev_terms= 10
use_sampling_sum_weights= True
mask
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 devided by
grid_step_factor
verbose= 1
mean_shift_for_mask_update= 0.1 Values of model shift in refinement to
updates the mask
cartesian_dynamics
temperature= 300
number_of_steps= 200
time_step= 0.0005
n_print= 100
verbose= -1
simulated_annealing
start_temperature= 5000
final_temperature= 300
cool_rate= 100
number_of_steps= 25
time_step= 0.0005
n_print= 100
update_grads_shift= 0.3
refine_sites= True
refine_adp= False
max_number_of_iterations= 25
mode= every_macro_cycle *second_and_before_last once first
verbose= -1
target_weights
wxc_scale= 0.5
wxu_scale= 1.0
wc= 1.0
wu= 1.0
fix_wxc= None
fix_wxu= None
allow_automatic_adjustment= False
delta_r_free_r_work= 6.0
wxc_scale_drop= 3.0
wxu_scale_drop= 3.0
max_number_of_macro_cycles= 12
optimize_wxc= False
optimization_criterion= *r_free gradient_angle
optimize_wxu= False
shake_sites= True
shake_adp= 10.0
regularize_ncycles= 50
gradient_filtering= True
gradient_filtering_method= *cns new
rmsd_cutoff_for_gradient_filtering= 3.0
verbose= 1
neutrons
wxnc_scale= 1.0
wxnu_scale= 1.0
dbe
b_iso_max= 100.0
occupancy_min= -1.0
occupancy_max= 1.5
ias_b_iso_max= 100.0
ias_b_iso_min= 0.0
ias_occupancy_min= 0.01
ias_occupancy_max= 3.0
initial_dbe_occupancy= 1.0
build_dbe_types= L R B BH
use_map= True
build_only= False
file_prefix= None
peak_search_map
map_type= *k*Fobs-n*Fmodel m*Fobs-D*Fmodel
grid_step= 0.1
scaling= *volume sigma
ls_target_names
target_name= *ls_wunit_k1 ls_wunit_k2 ls_wunit_kunit ls_wunit_k1_fixed
ls_wunit_k1ask3_fixed ls_wexp_k1 ls_wexp_k2 ls_wexp_kunit
ls_wff_k1 ls_wff_k2 ls_wff_kunit ls_wff_k1_fixed
ls_wff_k1ask3_fixed lsm_kunit lsm_k1 lsm_k2 lsm_k1_fixed
lsm_k1ask3_fixed
neutron
low_resolution= None
high_resolution= None
twinning
twin_law= None
detwin
mode= algebraic proportional *auto
map_types
twofofc= *two_m_dtfo_d_fc two_dtfo_fc
fofc= *m_dtfo_d_fc gradient m_gradient
aniso_correct= False
structure_factors_and_gradients_accuracy
algorithm= *fft direct
cos_sin_table= False
grid_resolution_factor= 1/3.
quality_factor= None
u_base= None
b_base= None
wing_cutoff= None
exp_table_one_over_step_size= None
r_free_flags
fraction= 0.1
max_free= 2000
lattice_symmetry_max_delta= 5.0 Tolerance used in the determination of
the highest lattice symmetry. Can be thought
of as angle between lattice vectors that
should line up perfectly if the symmetry is
ideal. A typical value is 3 degrees.
use_lattice_symmetry= True When generating Rfree flags, do so in the
asymmetric unit of the highest lattice symmetry.
The result is an Rfree set suitable for twin
refinement.