Iamkaant at 20:17, 21 September 2026

2026-09-21T20:17:33Z

← Older revision		Revision as of 20:17, 21 September 2026
Line 111:		Line 111:
	=== 2D figure ===		=== 2D figure ===

	[[File:587277089.0.~~N_rigid~~.png\|thumb\|600px\|none\|2D figure for a molecule with three hierarchies. Top: all rigid fragments. Bottom: one panel per hierarchy.]]		[[File:587277089.0.N_rigi
			[[File:1512441678.0.N rigid.png\|thumb]]
			d.png\|thumb\|600px\|none\|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).		* Each rigid fragment is highlighted in its own color (colorblind-friendly Okabe–Ito palette).

Iamkaant: initial commit

2026-09-21T20:15:53Z

initial commit

New page

'''db2_viz.py''' is a stand-alone Python script that visualizes a DOCK 3.x [[All About DB2 Files|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.

__TOC__

== Background ==

A DB2 file holds one or more '''hierarchies'''. Each hierarchy is an entry that starts with <code>M</code> lines and ends with an <code>E</code> 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 <code>R</code> lines. Each <code>R</code> 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 ===

<code>R</code> lines do not store atom indices. The script finds each rigid atom by matching the <code>R</code> line coordinates to the <code>X</code> line coordinates (tolerance 0.001 Å). If a hierarchy has no <code>R</code> 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 <code>R</code> lines to identify the rigid fragment.

== Requirements ==

* Python 3.9 or later
* [https://www.rdkit.org RDKit], matplotlib and numpy

For example, with conda:

<pre>
conda create -n db2viz -c conda-forge python rdkit matplotlib numpy
conda activate db2viz
</pre>

PyMOL is only needed to open the <code>.pml</code> output. The script does not import PyMOL.

== Usage ==

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

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

=== Examples ===

2D figure only:
<pre>
python db2_viz.py 587277089.0.N.db2
</pre>

2D figure with atom names, plus a PyMOL script, an SDF file and an HTML viewer:
<pre>
python db2_viz.py 587277089.0.N.db2 --labels --pymol --sdf --html
</pre>

Export the first 50 sets of each hierarchy as PyMOL states:
<pre>
python db2_viz.py 587277089.0.N.db2 --pymol --all-sets --max-sets 50
</pre>

Hierarchies 1 and 3 only, using the lowest-energy set, with an SVG figure:
<pre>
python db2_viz.py 587277089.0.N.db2 --hierarchies 1,3 --set min -f svg
</pre>

Summary printed for the example file:
<pre>
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
</pre>

=== Options ===

{| class="wikitable"
! Option !! Description
|-
| <code>-o</code>, <code>--out PREFIX</code> || Output file prefix. Default: the input file name without <code>.db2</code> or <code>.db2.gz</code>.
|-
| <code>-f</code>, <code>--format {png,svg,pdf}</code> || Format of the 2D figure. Default: <code>png</code>.
|-
| <code>--set N</code> or <code>--set min</code> || Set (conformation) used for the 3D outputs and for stereochemistry. <code>N</code> is a 1-based set index. <code>min</code> picks the non-broken set with the lowest value in the first energy column of the <code>S</code> lines. Default: <code>1</code>.
|-
| <code>--hierarchies 1,3</code> || Use only these hierarchies. Default: all.
|-
| <code>--layout {auto,combined,panels,both}</code> || Layout of the 2D figure. <code>combined</code>: one panel with all rigid fragments. <code>panels</code>: one panel per hierarchy. <code>both</code>: both. <code>auto</code> (default): <code>both</code> if there is more than one hierarchy, otherwise <code>combined</code>.
|-
| <code>--show-h</code> || Draw hydrogens in the 2D figure.
|-
| <code>--labels</code> || Label the atoms in the 2D figure with their DB2 atom names.
|-
| <code>--no-2d</code> || Do not write the 2D figure.
|-
| <code>--pymol</code> || Write a PyMOL script (<code>.pml</code>).
|-
| <code>--sdf</code> || Write an SDF file with the 3D poses.
|-
| <code>--html</code> || Write an interactive 3D viewer (<code>.html</code>).
|-
| <code>--all-sets</code> || Export every set instead of one: as PyMOL states in the <code>.pml</code> file and as separate records in the SDF file. It does not affect the HTML viewer.
|-
| <code>--max-sets N</code> || With <code>--all-sets</code>, export only the first <code>N</code> sets of each hierarchy.
|-
| <code>--no-superpose</code> || 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 <code>PREFIX_rigid.EXT</code>. If the DB2 file contains more than one molecule, each molecule gets its own files, named <code>PREFIX_MOLNAME_rigid.EXT</code>. Hierarchies are grouped into molecules by the name on the first <code>M</code> line.

=== 2D figure ===

[[File:587277089.0.N_rigid.png|thumb|600px|none|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 <code>fake</code>).

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

=== PyMOL script (<code>--pymol</code>) ===

The <code>.pml</code> file contains all coordinates, so no other file is needed:

<pre>
pymol 587277089.0.N_rigid.pml
</pre>

* Each hierarchy is a separate object: <code>H1</code>, <code>H2</code>, and so on.
* The rigid atoms of each hierarchy are in a named selection: <code>H1_rigid</code>, <code>H2_rigid</code>, 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 <code>--all-sets</code>, each set is one state of the object.

Useful commands after loading:
<pre>
set grid_mode, 1 # show the hierarchies side by side
hide everything, elem H and neighbor elem C # hide nonpolar hydrogens
</pre>

=== SDF file (<code>--sdf</code>) ===

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

{| class="wikitable"
! Property !! Content
|-
| <code>hierarchy</code> || Hierarchy number
|-
| <code>set</code> || Set index
|-
| <code>set_energies</code> || Energy values from the <code>S</code> line of the set
|-
| <code>rigid_atom_indices</code> || 1-based indices of the rigid atoms
|-
| <code>rigid_atom_names</code> || DB2 names of the rigid atoms
|-
| <code>atom_names</code> || DB2 names of all atoms, in order
|}

=== HTML viewer (<code>--html</code>) ===

The HTML file is an interactive 3D viewer based on [https://3dmol.csb.pitt.edu 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 <code>--all-sets</code>, all sets of a hierarchy get the same transformation, so the states stay consistent with each other. Use <code>--no-superpose</code> 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 <code>X</code> lines of its conformations (<code>C</code> and <code>S</code> 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. <code>ar</code> bonds to <code>O.co2</code> or <code>C.cat</code> 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.
* '''<code>--set min</code>''' uses the first energy column of the <code>S</code> line header. It skips sets flagged as broken.
* <code>D</code> lines (clusters) are ignored.

== See also ==

* [[All About DB2 Files]]

DB2 Visualizer - Revision history

Iamkaant at 20:17, 21 September 2026

Iamkaant: initial commit