LigAlign
Lilien Lab
Department of Computer Science
Centre for Cellular and Biomolecular Research
University of Toronto
Documentation

# Tutorial

1. Load LigAlign. Begin by running PyMOL on the ligand_alignment.py extension. For example, start PyMOL, at the PyMOL prompt (in the PyMOL program), change into the directory containing the ligand_alignment.py file (to do this, type "cd directoryname" without the quotes and with your directory name in place of 'directoryname'). When you are in the correct directory, type the following command into the PyMOL prompt,
   run ligand_alignment.py
   The text "LigAlign loaded." should appear. If this welcome message does not appear, you are most likely not in the correct directory - seek the friendly help of your local computer guru.
2. At the PyMOL prompt, we can begin by running:
   ligalign 1xbb, 1opj
   which will align 1opj to 1xbb so as to minimize the RMSD between the bound imatinib ligands. This may take a few moments to fetch the PDB files. The ligand in 1xbb and the surface of the region near the ligand from 1xbb will be displayed both colored with the same color. Similarly, the ligand in 1opj and the surface near the ligand in 1opj are colored together. These colors are assigned randomly each time the ligalign command is executed; your colors may differ from the picture above.
3. As we can see, LigAlign populates the right pane with a number of interesting selections. For now, turn off the surfaces of the regions near the ligand by clicking on 1xbb_surface and 1opj_surface in the right pane. Then run
   ligalign_show_mapping 1opj
   to show the atom-to-atom mappings computed by LigAlign. All of the atoms of 1opj are shown mapped to the corresponding atoms within 1xbb (because it was the pivot-selection from the last executed ligalign command (in step 1)). When we are done viewing the atom mappings, turn off the atom mapping by clicking on mapping_1opj_1xbb in the right pane.
4. Clearly, the imatinib ligand has internal degrees of freedom. Perform a substructure-based alignment with
   ligalign_fragments 1xbb, 1opj
   Again, turn off the protein surfaces for now by clicking on the surface selections in the right pane. Also turn off 1xbb by clicking on it in the right pane. What we see left is the ligand for 1opj, along with a fragmentation of it into three pieces: 1opj_1, 1opj_2, and 1opj_3. The ligalign_fragments command will align each of these fragments, independently, to the 1xbb pivot.
   Turn on 1xbb by clicking it in the right pane. Notice how the fragments 1opj_1, 1opj_2, and 1opj_3 were aligned more closely to 1xbb than the rigid complete 1obj could be. Furthermore, each of the fragments has an independently computed corresponding protein surface. By examining 1opj_surface versus 1opj_3_surface, we can see how the local active site region is oriented relative to the aligned fragment of the ligand.
5. If we turn off all surfaces except for 1opj_surface and run
   ligalign_color 1xbb_surface, 1opj_surface
   we will get a map of the distance from the center of each residue in 1opj_surface to the closest residue in 1xbb_surface. Red means that the closest residue is far away (default: more than 4.5 angstroms) whereas green means that the closest residue is quite close (default: less than 0.5 angstroms).

# Commands

- ligalign pivot-selection [, target-selection [, target-selection2, ...]]
  Computes a rigid alignment of the ligands in the target-selection(s) to the ligand in the pivot-selection. If no target-selection is specified, LigAlign will attempt to find appropriate ligands in a ligand similarity database, and display the bound proteins. LigAlign will automatically fetch the necessary files from the PDB. If there are multiple bound ligands in the proteins, LigAlign will choose the ligand from target-selection that is most similar to a ligand in the pivot-selection.
- ligalign_fragments pivot, target-selection [, target-selection2, ...]
  When the target's ligand is flexible, the best rigid alignment can still have bad overlap in the active sites. ligalign_fragments performs a substructure alignment of the ligands. It duplicates the target protein, aligning pieces of the fragment independently. The choice of best fragmentation is controlled by the ligalign_set settings. As with the ligalign command, if no target-selection is specified, LigAlign will attempt to find appropriate ligands automatically. This command generates a quantity of output as it enumerates alternative fragmentations; this output can be useful to track progress of the fragmentation process.
- ligalign_reset_stored
  Clears LigAlign caches and calls PyMOL's reinitialize command
- ligalign_color pivot-selection, target-selection
  Colors the residues in target-selection based on how far they are from the closest residue in pivot-selection. The center of each residue in the target selection is computed by averaging the location of each atom in the residue. This is repeated for the residues in the pivot selection. The minimum distance from each center in the target to any center in the pivot is computed and the target residue colored based on this minimum distance. Red means far (by default, more than 4.5 angstroms) and green means close (by default, less than 0.5 angstroms), with the distances in between discretized into ten groups, each with a color interpolated between red and green.
- ligalign_show_mapping target-selection
  Draw dashed lines showing the atom-to-atom mappings from target-selection to the pivot for which target-selection was aligned.
- ligalign_viz [setting=1-8] [, full_residues=True|False] [, entire_protein=True|False]
  A number of useful vizualizations of the region near the ligand. The default is setting 7.
  - setting 1 selects the atoms from any of the bound proteins which are near the ligands and shows them as spheres, using the default PyMOL coloration.
  - setting 2 shows the same nearby protein atoms as setting 1, but makes the atom spheres small, to less obscure the ligand alignment.
  - setting 3 takes the same atoms as settings 1 and 2 and computes an electrostatic surface over them, then displaces this transparent closed consensus surface of the nearby atoms.
  - setting 4 shows the same consensus surface as setting 3, but makes it opaque.
  - setting 5 shows an open opaque consensus surface. This is the electrostatic surface where the edges of the active-site surface are computed to match the electrostatic surface of the rest of the protein, not just computed from the atoms near the ligands.
  - setting 6 shows the ligand as spheres and the active sites of any of the bound proteins as sticks.
  - setting 7 shows a closed surface which was computed independently over each target-selection.
  - setting 8 shows a closed surface and side-chains for each target-selection.
- ligalign_set [cutoff | max_splits | min_fragment_size | distant_residue_distance], value
  Changes a number of ligalign parameters
  - cutoff is the %RMSD decrease below which we no longer try to increase the number of fragments (default: 0.1, i.e. 10%)
  - max_splits is the maximum number of fragments to permit (default: None, i.e. infinitely many)
  - min_fragment_size is the minimum number of atoms in a fragment (default: 4)
  - distant_residue_distance is the number of angstroms beyond which ligalign_color will use bright red (default: 5.0)