Manipulations on a model in a PDB file including

The operations below can be applied to the whole model or selected parts (e.g. "modify.selection=chain A and backbone"). See examples below.

• shaking of coordinates (random coordinate shifts)
• rotation-translation shift of coordinates
• shaking of occupancies
• set occupancies to a value
• shaking of ADP (B-factors)
• shifting of ADP (addition of a constant value)
• scaling of ADP (multiplication by a constant value)
• setting ADP to a given value
• conversion to isotropic or anisotropic ADP
• removal of selected parts of a model
• renumbering of residues
• truncation to poly-ALA
• convert SeMet residues to Met
• adjust segid field in PDB format

Video Tutorial

The tutorial video is available on the Phenix YouTube channel and covers the following topics:

• basic overview
• how to run PDBTools via the GUI
• example 1: prepare model file for usage with lower resolution data
• example 2: convert all residues in a model to alanine

Graphical interface

As input, only a PDB file and appropriate geometry restraints (in CIF format are required. (The geometry restraints are actually optional if you uncheck the box "Stop for unknown residues", but they are strongly recommended.) Crystal symmetry is not essential but also recommended, and will be propagated to the output model.

Many different options are possible, only some of which are shown in the main window. The atom selection controls can be used to specify which part of the model will be affected by various changes, or to eliminate parts of the model. The operations on coordinates, B-factors, and occupancies also have separate (optional) atom selections.

(Note: in past versions PDBTools was also responsible for geometry minimization and addition of hydrogen atoms using Reduce; these methods have been moved to the programs phenix.geometry_minimization and phenix.ready_set, respectively.)

Command-line use

In the absence of a CRYST1 record in the PDB file, functionality that doesn't require knowledge of the crystal symmetry is still available. To enable the full functionality, the crystal symmetry can be specified externally (e.g. via the --symmetry option).

Some specific examples:

1) Type phenix.pdbtools from the command line for instructions:

% phenix.pdbtools

2) To see all default parameters:

% phenix.pdbtools --show-defaults=all

3) Suppose a PDB model consist of three chains A, B and C and some water molecules. Remove all atoms in chain C and all waters:

% phenix.pdbtools model.pdb remove="chain C or water"

or one can achieve exactly the same result with equivalent command:

% phenix.pdbtools model.pdb keep="chain A or chain B"

or:

% phenix.pdbtools model.pdb keep="not(chain C or water)"

or finally:

% phenix.pdbtools model.pdb remove="not(chain A or chain B)"

The result of all four equivalent commands above will be a new PDB file containing chains A and B only. Important: the commands keep and remove cannot be used simultaneously.

4) Remove all but backbone atoms and set all b-factors to 25:

% phenix.pdbtools model.pdb keep=backbone set_b_iso=25

5) Suppose a PDB model consist of three chains A, B and C and some water molecules. Remove all but backbone atoms and set b-factors to 25 for chain C atoms:

% phenix.pdbtools model.pdb keep=backbone set_b_iso=25 modify.selection="chain C"

6) Show cmprehensive model statistics:

% phenix.pdbtools model.pdb model_statistics=true

List of all available keywords

• use_neutron_distances = False Use neutron X-H distances (which are longer than X-ray ones)
• model_statistics = None
• stop_for_unknowns = True
• job_title = None Job title in PHENIX GUI, not used on command line
• modify
  • remove = None Selection for the atoms to be removed
  • keep = None Select atoms to keep
  • put_into_box_with_buffer = None Move molecule into center of box.
  • selection = None Selection for atoms to be modified
  • change_of_basis = None Apply change-of-basis operator (e.g. reindexing operator) to the coordinates and symmetry. Example: a,c,b .
  • renumber_residues = False Re-number residues
  • increment_resseq = None Increment residue number
  • truncate_to_polyala = False Truncate a model to poly-Ala.
  • remove_alt_confs = False Deletes atoms whose altloc identifier is not blank or A , and resets the occupancies of the remaining atoms to 1.0.
  • always_keep_one_conformer = False Modifies behavior of remove_alt_confs so that residues with no conformer labeled blank or A are not deleted. Silent if remove_alt_confs is False.
  • set_chemical_element_simple_if_necessary = None Make a simple guess about what the chemical element is (based on atom name and the way how it is formatted) and write it into output file.
  • set_seg_id_to_chain_id = False Sets the segID field to the chain ID (padded with spaces).
  • clear_seg_id = False Erases the segID field.
  • convert_semet_to_met = False
  • convert_met_to_semet = False
  • remove_first_n_atoms_fraction = None
  • random_seed = None Random seed
  • move_waters_last = False Transfer waters to the end of the model. Addresses some limitations of water picking in phenix.refine.
  • adpScope of options to modify ADP of selected atoms
    • atom_selection = None Selection for atoms to be modified. Overrides parent-level selection.
    • randomize = False Randomize ADP within a certain range
    • set_b_iso = None Set ADP of atoms to set_b_iso
    • convert_to_isotropic = False Convert atoms to isotropic
    • convert_to_anisotropic = False Convert atoms to anisotropic
    • shift_b_iso = None Add shift_b_iso value to ADP
    • scale_adp = None Multiply ADP by scale_adp
  • sitesScope of options to modify coordinates of selected atoms
    • atom_selection = None Selection for atoms to be modified. Overrides parent-level selection.
    • shake = None Randomize coordinates with mean error value equal to shake
    • switch_rotamers = max_distant min_distant exact_match fix_outliers
    • translate = 0 0 0 Translational shift (x,y,z)
    • rotate = 0 0 0 Rotational shift (x,y,z)
    • euler_angle_convention = *xyz zyz Euler angles convention to be used for rotation
  • occupanciesScope of options to modify occupancies of selected atoms
    • atom_selection = None Selection for atoms to be modified. Overrides parent-level selection.
    • randomize = False Randomize occupancies within a certain range
    • set = None Set all or selected occupancies to given value
    • normalize = False Reset the sum of occupancies for each residue to 1.0. Note that this will be performed before any atoms are removed.
  • rotate_about_axis
    • axis = None
    • angle = None
    • atom_selection = None
  • rename_chain_idRename chains
    • old_id = None
    • new_id = None
  • set_charge
    • charge_selection = None
    • charge = None
  • outputWrite out file with modified model (file name is defined in write_modified)
    • file_name = None Default is the original file name with the file extension replaced by _modified.pdb .
    • format = *pdb mmcif Choose the output format of coordinate file (PDB or mmCIF)
• input
  • pdb
    • file_name = None Model file(s) name (PDB)
  • monomer_library
    • file_name = None Monomer file(s) name (CIF)
  • crystal_symmetryUnit cell and space group parameters
    • unit_cell = None
    • space_group = None
• pdb_interpretation
  • sort_atoms = True
  • superpose_ideal_ligand = *None all SF4 F3S
  • flip_symmetric_amino_acids = False
  • disable_uc_volume_vs_n_atoms_check = False
  • correct_hydrogens = True
  • c_beta_restraints = True
  • use_neutron_distances = False Use neutron X-H distances (which are longer than X-ray ones)
  • disulfide_bond_exclusions_selection_string = None
  • exclusion_distance_cutoff = 3 If SG of CYS forming SS bond is closer than this distance to an atom that it may coordinate then this SG is excluded from SS bond.
  • link_distance_cutoff = 3
  • disulfide_distance_cutoff = 3
  • add_angle_and_dihedral_restraints_for_disulfides = True
  • dihedral_function_type = *determined_by_sign_of_periodicity all_sinusoidal all_harmonic
  • chir_volume_esd = 0.2
  • max_reasonable_bond_distance = 50.0
  • nonbonded_distance_cutoff = None
  • default_vdw_distance = 1
  • min_vdw_distance = 1
  • nonbonded_buffer = 1 **EXPERIMENTAL, developers only**
  • nonbonded_weight = None Weighting of nonbonded restraints term. By default, this will be set to 16 if explicit hydrogens are used (this was the default in earlier versions of Phenix), or 100 if hydrogens are missing.
  • const_shrink_donor_acceptor = 0.6 **EXPERIMENTAL, developers only**
  • vdw_1_4_factor = 0.8
  • min_distance_sym_equiv = 0.5
  • custom_nonbonded_symmetry_exclusions = None
  • translate_cns_dna_rna_residue_names = None
  • proceed_with_excessive_length_bonds = False
  • restraints_library
    • cdl = True Use Conformation Dependent Library (CDL) for geometry minimization restraints
    • omega_cdl = False Use Omega Conformation Dependent Library (omega-CDL) for geometry minimization restraints
    • rdl = False
    • hpdl = False
  • secondary_structure
    • enabled = False Turn on secondary structure restraints (main switch)
    • protein
      • enabled = True Turn on secondary structure restraints for protein
      • search_method = *ksdssp mmtbx_dssp from_ca cablam Particular method to search protein secondary structure.
      • distance_ideal_n_o = 2.9 Target length for N-O hydrogen bond
      • distance_cut_n_o = 3.5 Hydrogen bond with length exceeding this value will not be established
      • remove_outliers = True If true, h-bonds exceeding distance_cut_n_o length will not be established
      • restrain_hbond_angles = True
      • helix
        • serial_number = None
        • helix_identifier = None
        • enabled = True Restrain this particular helix
        • selection = None
        • helix_type = *alpha pi 3_10 unknown Type of helix, defaults to alpha. Only alpha, pi, and 3_10 helices are used for hydrogen-bond restraints.
        • sigma = 0.05
        • slack = 0
        • top_out = False
        • hbond
          • donor = None
          • acceptor = None
      • sheet
        • enabled = True Restrain this particular sheet
        • first_strand = None
        • sheet_id = None
        • sigma = 0.05
        • slack = 0
        • top_out = False
        • strand
          • selection = None
          • sense = parallel antiparallel *unknown
          • bond_start_current = None
          • bond_start_previous = None
        • hbond
          • donor = None
          • acceptor = None
    • nucleic_acid
      • enabled = True Turn on secondary structure restraints for nucleic acids
      • hbond_distance_cutoff = 3.4 Hydrogen bonds with length exceeding this limit will not be established
      • angle_between_bond_and_nucleobase_cutoff = 35.0 If angle between supposed hydrogen bond and basepair plane (defined by C4, C5, C6 atoms) is less than this value (in degrees), the bond will not be established.
      • base_pair
        • enabled = True Restraint this particular base-pair
        • base1 = None Selection string selecting at least one atom in the desired residue
        • base2 = None Selection string selecting at least one atom in the desired residue
        • saenger_class = 0 Type of base-pairing
        • restrain_planarity = False Apply planarity restraint to this base-pair
        • planarity_sigma = 0.176
        • restrain_hbonds = True Restrain hydrogen bonds length for this base-pair
        • restrain_hb_angles = True Restrain angles around hydrogen bonds for this base-pair
        • restrain_parallelity = True Apply parallelity restraint to this base-pair
        • parallelity_target = 0
        • parallelity_sigma = 0.0335
      • stacking_pair
        • enabled = True Restraint this particular base-pair
        • base1 = None Selection string selecting at least one atom in the desired residue
        • base2 = None Selection string selecting at least one atom in the desired residue
        • angle = 0
        • sigma = 0.027
  • reference_coordinate_restraintsRestrains coordinates in Cartesian space to stay near their starting positions. This is intended for use in generating simulated annealing omit maps, to prevent refined atoms from collapsing in on the region missing atoms. For conserving geometry quality at low resolution, the more flexible reference model restraints should be used instead.
    • enabled = False
    • exclude_outliers = True
    • selection = all
    • sigma = 0.2
    • limit = 1.0
    • top_out = False
  • automatic_linking
    • link_all = False If True, bond restraints will be generated for any appropriate ligand-protein or ligand-nucleic acid covalent bonds. This includes sugars, amino acid modifications, and other prosthetic groups.
    • link_none = False
    • link_metals = False
    • link_residues = False
    • link_amino_acid_rna_dna = False
    • link_carbohydrates = True
    • link_ligands = True
    • metal_coordination_cutoff = 3.5
    • amino_acid_bond_cutoff = 1.9
    • inter_residue_bond_cutoff = 2.2
    • buffer_for_second_row_elements = 0.5
    • carbohydrate_bond_cutoff = 1.99
    • ligand_bond_cutoff = 1.99
  • include_in_automatic_linking
    • selection_1 = None
    • selection_2 = None
    • bond_cutoff = 4.5
  • exclude_from_automatic_linking
    • selection_1 = None
    • selection_2 = None
  • apply_cis_trans_specification
    • cis_trans_mod = cis *trans
    • residue_selection = None Residues containing C-alpha atom of omega dihedral
  • apply_cif_restraints
    • restraints_file_name = None
    • residue_selection = 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
    • ramachandran_restraints = False Restrains peptide backbone to fall within allowed regions of Ramachandran plot. Although it does not eliminate outliers, it can significantly improve the percent favored and percent outliers at low resolution. Probably not useful (and maybe even harmful) at resolutions much higher than 3.5A.
    • cis_threshold = 45
    • apply_all_trans = False
    • discard_omega = False
    • discard_psi_phi = True
    • apply_peptide_plane = False
    • omega_esd_override_value = None
    • rama_weight = 1.0
    • scale_allowed = 1.0
    • rama_potential = *oldfield emsley
    • rama_selection = None
    • rama_exclude_sec_str = False
    • oldfield
      • esd = 10.0
      • weight_scale = 1.0
      • dist_weight_max = 10.0
      • weight = None
      • plot_cutoff = 0.027
  • rna_sugar_pucker_analysis
    • bond_min_distance = 1.2
    • bond_max_distance = 1.8
    • epsilon_range_min = 155.0
    • epsilon_range_max = 310.0
    • delta_range_2p_min = 129.0
    • delta_range_2p_max = 162.0
    • delta_range_3p_min = 65.0
    • delta_range_3p_max = 104.0
    • p_distance_c1p_outbound_line_2p_max = 2.9
    • o3p_distance_c1p_outbound_line_2p_max = 2.4
    • bond_detection_distance_tolerance = 0.5
  • show_histogram_slots
    • bond_lengths = 5
    • nonbonded_interaction_distances = 5
    • bond_angle_deviations_from_ideal = 5
    • dihedral_angle_deviations_from_ideal = 5
    • chiral_volume_deviations_from_ideal = 5
  • show_max_items
    • not_linked = 5
    • bond_restraints_sorted_by_residual = 5
    • nonbonded_interactions_sorted_by_model_distance = 5
    • bond_angle_restraints_sorted_by_residual = 5
    • dihedral_angle_restraints_sorted_by_residual = 3
    • chirality_restraints_sorted_by_residual = 3
    • planarity_restraints_sorted_by_residual = 3
    • residues_with_excluded_nonbonded_symmetry_interactions = 12
    • fatal_problem_max_lines = 10
  • ncs_group
    • reference = None Residue selection string for the complete master NCS copy
    • selection = None Residue selection string for each NCS copy location in ASU
  • ncs_search
    • enabled = False Use NCS restraints or constraints in refinement (can be determined automatically)
    • exclude_selection = "not (protein or nucleotide) or element H or element D" Atoms selected by this selection will be excluded from the model before search procedures will run.
    • chain_similarity_threshold = 0.85 Threshold for similarity between matching chains. A smaller value cause more chains to be grouped together and can lower the number of common residues
    • chain_max_rmsd = 2. limit of rms difference between chains to be considered as copies
    • residue_match_radius = 4.0 Max allowed distance difference between pairs of matching atoms of two residues
  • 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
    • 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
    • dihedral
      • action = *add delete change
      • atom_selection_1 = None
      • atom_selection_2 = None
      • atom_selection_3 = None
      • atom_selection_4 = None
      • angle_ideal = None
      • sigma = None
      • periodicity = None
    • planarity
      • action = *add delete change
      • atom_selection = None
      • sigma = None
    • parallelity
      • action = *add delete change
      • atom_selection_1 = None
      • atom_selection_2 = None
      • sigma = 0.027
      • target_angle_deg = 0
  • remove
    • angles = None
    • dihedrals = None
    • chiralities = None
    • planarities = None
    • parallelities = None