DB2 Visualizer

db2_viz.py is a stand-alone Python script that visualizes a DOCK 3.x DB2 file and highlights the rigid fragment of each hierarchy. It draws a 2D depiction with each rigid fragment in its own color, and can also write 3D files (a PyMOL script, an SDF file and an interactive HTML viewer) with the same highlighting.

Use it to check which rigid fragments were used to build a ligand's DB2 file, to compare the hierarchies of one molecule, or to look at the conformations (sets) stored in the file.

Background

A DB2 file holds one or more hierarchies. Each hierarchy is an entry that starts with M lines and ends with an E line. The hierarchies of one molecule are built around different rigid fragments. DOCK places the rigid fragment first by matching it to the receptor spheres, and then builds the flexible part of the ligand from the stored conformations.

The rigid fragment of a hierarchy is given by its R lines. Each R line holds the coordinates of one rigid atom. See All About DB2 Files for the full description of the line types.

How the rigid atoms are found

R lines do not store atom indices. The script finds each rigid atom by matching the R line coordinates to the X line coordinates (tolerance 0.001 Å). If a hierarchy has no R lines, the script uses the atoms of conformation 1.

Note: conformation 1 is not always the whole rigid fragment. It can be a single atom, with the rest of the rigid fragment spread over the next few conformations. Always use the R lines to identify the rigid fragment.

Requirements

• Python 3.9 or later
• RDKit, matplotlib and numpy

For example, with conda:

conda create -n db2viz -c conda-forge python rdkit matplotlib numpy
conda activate db2viz

PyMOL is only needed to open the .pml output. The script does not import PyMOL.

Usage

On Gimel:

conda activate <your Python env>
python /mnt/nfs/exa/work/ak87/UCSF/SCRIPTS/DOCKING/db2_viz.py ligand.db2 [options]

The input can be a plain .db2 file or a gzipped .db2.gz file. By default the script writes only the 2D figure. Add --pymol, --sdf or --html to also write 3D files.

Examples

2D figure only:

python db2_viz.py 587277089.0.N.db2

2D figure with atom names, plus a PyMOL script, an SDF file and an HTML viewer:

python db2_viz.py 587277089.0.N.db2 --labels --pymol --sdf --html

Export the first 50 sets of each hierarchy as PyMOL states:

python db2_viz.py 587277089.0.N.db2 --pymol --all-sets --max-sets 50

Hierarchies 1 and 3 only, using the lowest-energy set, with an SVG figure:

python db2_viz.py 587277089.0.N.db2 --hierarchies 1,3 --set min -f svg

Summary printed for the example file:

587277089.0: 3 hierarchies, 48 atoms, 52 bonds
  H1:  1353 confs   600 sets  rigid (7): C2 C3 C4 C5 C6 C7 S1
  H2:   763 confs   600 sets  rigid (15): C6 C7 N1 C8 C9 C10 C19 N3 N4 C20 C21 F1 F2 F3 C22
  H3:   800 confs   600 sets  rigid (12): C10 C11 C12 C13 O3 C14 C15 C16 Br1 C17 N2 C18

Options

Option	Description
-o, --out PREFIX	Output file prefix. Default: the input file name without .db2 or .db2.gz.
-f, --format {png,svg,pdf}	Format of the 2D figure. Default: png.
--set N or --set min	Set (conformation) used for the 3D outputs and for stereochemistry. N is a 1-based set index. min picks the non-broken set with the lowest value in the first energy column of the S lines. Default: 1.
--hierarchies 1,3	Use only these hierarchies. Default: all.
--layout {auto,combined,panels,both}	Layout of the 2D figure. combined: one panel with all rigid fragments. panels: one panel per hierarchy. both: both. auto (default): both if there is more than one hierarchy, otherwise combined.
--show-h	Draw hydrogens in the 2D figure.
--labels	Label the atoms in the 2D figure with their DB2 atom names.
--no-2d	Do not write the 2D figure.
--pymol	Write a PyMOL script (.pml).
--sdf	Write an SDF file with the 3D poses.
--html	Write an interactive 3D viewer (.html).
--all-sets	Export every set instead of one: as PyMOL states in the .pml file and as separate records in the SDF file. It does not affect the HTML viewer.
--max-sets N	With --all-sets, export only the first N sets of each hierarchy.
--no-superpose	Keep each hierarchy in its original DB2 coordinate frame. By default, the 3D outputs superpose all hierarchies onto the first one.

Output

All output files are named PREFIX_rigid.EXT. If the DB2 file contains more than one molecule, each molecule gets its own files, named PREFIX_MOLNAME_rigid.EXT. Hierarchies are grouped into molecules by the name on the first M line.

2D figure

File:587277089.0.N rigid.png

2D figure for a molecule with three hierarchies. Top: all rigid fragments. Bottom: one panel per hierarchy.

• Each rigid fragment is highlighted in its own color (colorblind-friendly Okabe–Ito palette).
• An atom that belongs to more than one rigid fragment is shown in all of their colors.
• If there is more than one hierarchy, a legend lists each hierarchy with the size of its rigid fragment and its numbers of conformations and sets.
• The figure title is the molecule name, followed by the SMILES string if the file contains a real one (not fake).

The structure is built from the A and B lines, so the script works even when the M line SMILES is fake.

PyMOL script (--pymol)

The .pml file contains all coordinates, so no other file is needed:

pymol 587277089.0.N_rigid.pml

• Each hierarchy is a separate object: H1, H2, and so on.
• The rigid atoms of each hierarchy are in a named selection: H1_rigid, H2_rigid, and so on.
• Rigid atoms are drawn as thick sticks with small spheres. Their carbons and hydrogens use the same color as in the 2D figure. The flexible part is drawn as thin gray sticks.
• Atom names are the DB2 atom names.
• With --all-sets, each set is one state of the object.

Useful commands after loading:

set grid_mode, 1                             # show the hierarchies side by side
hide everything, elem H and neighbor elem C  # hide nonpolar hydrogens

SDF file (--sdf)

The SDF file has one record per hierarchy, or one record per set with --all-sets. Each record stores these properties:

Property	Content
hierarchy	Hierarchy number
set	Set index
set_energies	Energy values from the S line of the set
rigid_atom_indices	1-based indices of the rigid atoms
rigid_atom_names	DB2 names of the rigid atoms
atom_names	DB2 names of all atoms, in order

HTML viewer (--html)

The HTML file is an interactive 3D viewer based on 3Dmol.js that opens in any web browser.

• Radio buttons switch between hierarchies. Each button shows the hierarchy's color and its rigid atoms.
• A checkbox shows or hides the hydrogens.
• Hovering over an atom shows its DB2 atom name.

The page loads 3Dmol.js from a CDN, so it needs an internet connection.

Notes and limitations

• Superposition. Each hierarchy has its own coordinate frame, with its rigid fragment near the origin. The 3D outputs therefore superpose each hierarchy onto hierarchy 1 by least-squares fitting of all atoms of the chosen set. With --all-sets, all sets of a hierarchy get the same transformation, so the states stay consistent with each other. Use --no-superpose to keep the original coordinates, for example to compare them with the sphere positions.
• Coordinates of a set. The full coordinates of a set are the union of the X lines of its conformations (C and S lines). The script prints a warning if some atoms are left without coordinates.
• Formal charges. DB2 files do not store formal charges, so the script guesses them from atom valence. For example, 4-valent nitrogen gets +1 and 1-valent oxygen gets −1. ar bonds to O.co2 or C.cat atoms (carboxylate, phosphate, amidinium) are turned into one double bond and single bonds. If RDKit cannot sanitize the molecule, the script prints a note and draws the structure without sanitization. In that case, the figure shows no stereochemistry.
• --set min uses the first energy column of the S line header. It skips sets flagged as broken.
• D lines (clusters) are ignored.

See also

• All About DB2 Files