Note that the aB_covalent_ligand command-line tool tries to simplify and automate most manual steps in the description below. Please use

   aB_covalent_ligand -h

for help about the usage syntax. This works especially well for cases of single linkages, but can also be used for multi-linkage compounds (see various posts on the buster-discuss mailing list).

How to use grade to get BUSTER restraints for a covalently bound

ligand, 3b0r/GW9 example.


  • If you have a ligand that covalently binds to an amino acid then you have two choices to represent it in BUSTER refinement:
    • Leave the amino acid as a standard and use a PDB LINK line to indicate that there is a covalent link. This tutorial covers how to do this with grade restraints for the ligand and across the LINK.
    • An alternative is to define the complete amino acid and the chemical modifying group as a single residue and create a dictionary for this entity. The modified amino acid needs to have standard atom names for main chain atom. It is best to use grade having prepared a mol2 file for the complete modified amino acid that has the correct main chain atoms. A useful starting point is look at a chemically modified amino acid such as CGA in ligand expo grade (in particular grade_PDB_ligand) and BUSTER can handle this without any intervention. Although in some ways simpler users prefer the LINK route!
  • Defining good restraints for a covalent LINK between the protein and a ligand is (currently) a bit involved. This is because BUSTER is based on TNT for the geometry function it is necessary to create a special kind of TNT restraint dictionary for the link. Although we have switched to using the standard cif format restraint dictionaries for isolated ligands it is not trivial to do so for covalently linked ligands.
  • As a practical example we will use the PDB entry 3b0r.
    • RCSB page on 3b0r
    • 3b0r is 2.15 Å resolution structure of PPAR gamma ligand binding domain.
    • It has the ligand GW9662 bound:
    • GW9.png
    • In the case of 3b0r it is bound with the chlorine atom missing and in its place a covalent bond to atom SG from residue CYS 285.
    • The link is defined in the pdb file for both the A chain and B chain.
grep LINK 3b0r/3b0r.pdb 
LINK         SG  CYS A 285                 C9  GW9 A   1     1555   1555  1.80  
LINK         SG  CYS B 285                 C9  GW9 B   1     1555   1555  1.80 

Starting files.

Control standard BUSTER refinement with no additional dictionaries.

  • As a control lets do a standard BUSTER refinement on 3b0r.
  • We will first need a restraint dictionary for the GW9 ligand in its standard unmodified form.
    • To do this you can either use the grade program (if you have a CSD mogul licence)
            grade_PDB_ligand GW9
    • In either case download the cif dictionary GW9.grade_PDB_ligand.cif and "ideal" pdb coordinates GW9.grade_PDB_ligand.pdb
    • then run the refinement
            refine -p 3b0r.pdb -m 3b0r.mtz -l GW9.grade_PDB_ligand.cif -d 01_control > 01_control.log

If you look at the detailed log files for the run

  • It can be seen that because the CYS SG to GW9 C9 links are not "standard" a bond restraint of 1.78 with a sigma of 0.05 Angs is used, but no angle restraints are imposed.
  • This simplistic approach is crude but works OK in this case because the density is good.
  • But for lower resolution/noisy maps the approach would likely lead to some very poor density. Lets see how we can do better.

Producing the extended ligand cif dictionary using ccp4i sketcher, openbabel and grade

To produce decent restraints for the CYS to GW9 link we will produce a dictionary for the "extended ligand". We define the "extended ligand" as consisting of the GW9 ligand after it has been modified included atoms from the amino acid side chain up to the CA atom.

In our case we want to

  • take the GW9 residue
  • remove the chlorine atom
  • replace with a sulfur atom, calling this "SG",
  • then add an acyl group with the atoms calling the atoms "CB" and "CA":
  • GW9_mod.GIF
  • This needs to be done preserving the GW9 atom names in the process with the results being converted to reasonable 3D model in mol2 format suitable for grade, or the Grade Web Server.

The above can all be achieved using the ccp4i sketcher and OpenBabel - but you may prefer to use another molecular sketcher (provided that it knows about atom names).

The ccp4i monomer library sketcher can be used for the operation. We will start with GW9 ideal coordinates that we have created above (or use GW9.grade_PDB_ligand.pdb)

  • First start ccp4i and select the option "Refinement", "Restraint Preparation", "Monomer Library Sketcher".
  • Then in the Sketcher, select "File", "Read File", "Read PDB File" and navigate/select the file GW9.grade_PDB_ligand.pdb.
  • Answer "No" in the run libcheck now popup.
  • In the Sketcher: delete the chlorine atom and add three atoms. Then use the pull down menus on the right hand side to change the element type for the sulfur atom and to change the atom names as shown:
    • ccp4i_library_sketcher.png
  • Once you have made the changes, select "File", "Create Library Description" and select the option "displayed structure" in the "Create description from" option. Change the fields "Job title", "Unique identifier" and "Full name" to GW9CYS, as shown here:
    • create_dictionary_entry_new.png
  • Select "Run" and "Run now".
  • When the job has finished a rather mangled GW9CYS ligand will be displayed. But do not worry: what we are after is the file GW9CYS_mon_lib.cif created by the job. For me this appears in the directory that ccp4i was run from. Locate this file and copy it into your working directory. Leave ccp4i.

Then run:

grade -in GW9CYS_mon_lib.cif -resname GW9 -name extended_GW9_ligand_modified_with_CYS

The result of this is a cif restraint dictionary for the "extended" GW9 residue: grade-GW9.cif. This dictionary can be used for the ligand in BUSTER refinements and also contains the information we need for good link restraints (next section).

If you want you can check that the dictionary is OK by loading it and the ideal coordinates into coot.

coot -p grade-GW9.pdb --dict grade-GW9.cif

Producing TNT-style link dictionary from extended cif dictionary.

This is easily accomplished using the perl script that is distributed with BUSTER releases. First get its help message -h


# use -man option to see full copyright information
Usage: -icif grade-INH.cif -odic
    SER-INH-link.dic -3let SER -aatnam OG -latnam C10

      For help: -h 

      command line "options": 
            -h                      optional, print this help message and terminate.
            -icif input.cif         must be specified, input .cif file for the extended ligand
            -odic output.dic        must be specified, output .dic file that will contain the link dictionary. 
            -f                      optional, overwrite existing output file
            -3let SER               must be specified, 3 letter code for the amino acid that starts the covalent link, for instance "SER" or "CYS"
            -aatnam OG              must be specified, atom name in the amino acid that is linked to the ligand, for instance "OG" in SER or "NZ" in LYS
            -latnam C10             must be specified,atom name in the ligand that is linked to the amino acid, see atom name notes below 
      Atom name notes
            This utility assumes that any atom with an name in array @aa_sidechain_anames is part of the amino acid. Any atom with a different name is not.

To use on the extended cif produced above: -icif grade-GW9.cif -odic grade-GW9CYS-link.dic -3let CYS -aatnam SG -latnam C9

will report:

# use -man option to see full copyright information
# Converting dictionary grade-GW9.cif with refmacdict2tnt resulted in 130 lines starting GEOMETRY, for residue type GW9
# three letter code for amino acid that is modified is CYS
# success identified 8 link type restraints and have written them to file grade-GW9CYS-link.dic

The resulting link dictionary is grade-GW9CYS-link.dic - it contains the following:

# tnt dictionary to link amino acid CYS atom SG
# to ligand GW9 atom C9 using restraint type ZGW9
# produced by jiffy
GEOMETRY ZGW9 BOND 1.770 0.012 SG +C9
GEOMETRY ZGW9 ANGLE 120.7 2.7 SG +C9 +C10
GEOMETRY ZGW9 ANGLE 120.6 1.5 SG +C9 +C8
GEOMETRY ZGW9 TORSION 10000.0 1000000.0 +C10 +C9 SG CB
GEOMETRY ZGW9 TORSION 10000.0 1000000.0 +C9 SG CB CA
GEOMETRY ZGW9 PLANE 4 0.02 +C9 +C10 SG +C8
  • The first three lines allow our MakeLINK program to understand that the link restraints "ZGW9" should be used for the link between CYS SG and GW9 C9 atoms.
  • The restraints within the files are the restraints for the link. As well as bond restraint based on Mogul there are three angle restraints and a plane restraint holding SG atom in the plane of phenyl ring.

The next section explains how to use the TNT-style link dictionary that we have just produced in BUSTER.

Using the extended-ligand cif and TNT-style link dictionary in BUSTER.

We will use the

The first thing I would recommend is to add hydrogen atoms to the ligand. This is a good idea because it clearly shows what the ligand chemistry is. At this resolution (2.1 Angs) I would do this just for the ligand and use zero occupancy for these hydrogen atoms. You just need the extended GW9 cif dictionary for this:

hydrogenate -p 3b0r.pdb -o 3b0r_GW9addh.pdb -l grade-GW9.cif -ligonly -zero


hydrogenate uses the 'reduce' tool; if you publish work which uses it,
please cite

Word, et. al. (1999) J. Mol. Biol. 285, 1735-1747.
For more information see
Producing CONECT records suitable for molprobity.reduce on GW9

Then BUSTER can be run to use the grade restraints for the covalent link:

refine -p 3b0r_GW9addh.pdb -m 3b0r.mtz \
  -l grade-GW9.cif -l grade-GW9CYS-link.dic   \
  -d 02_grade_covalent -report >  02_grade_covalent.log
  • Note that you have to specify both the cif restraint dictionary for the "extended" GW9 residue, the link dictionary and the sequence file.

Task accomplished, we have done a refinement for a covalently linked GW9 using a grade dictionary for the link (check LIST.html it will have no WARNINGS about missing angles etc. The covalently linked ligand in the B chain:

  • 02_grade_covalent_coot_1p3.png

In this case the better restraints make little difference because the density is good and the covalent link only changes the ligand chemistry a little. This is not the case in the Advanced tutorial on 1b0e and SEI.

How-to summary for this method

In summary:

  1. Start with the unmodified ligand pdb file including hydrogen atoms (from ligand expo, grade or somewhere else).
  2. Use the ccp4i sketcher to produce an "extended" ligand that is add atoms to get the ligand plus the amino acid side chain up to atom CA, making sure all heavy atoms have the correct amino acid names. Get cif dictionary file out of ccp4i.
  3. Use the ccp4i produced dictionary as an input to grade.
  4. Use script to produce TNT-style link dictionary from extended ligand cif dictionary.
  5. Make sure protein pdb file has correct LINK line(s)
  6. In BUSTER refine use both the extended ligand cif dictionary and link .dic dictionary.

Page by Oliver Smart original version 03 June 2012, updated June 2013 for ccp4 6.3.0, last updated Apr 2016. Address problems, corrections and clarifications to